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Preface 


CICS® Explorer™ is the latest significant evolution in the management and 
analysis of your CICS environment. It is a statement of intent from the CICS 
Development organization, which is determined to ensure you can manage your 
CICS estate in a simple and easily extensible way, using a combination of the 
following approaches: 

► Tried and trusted CICS expertise and technology 

► The widely accepted user interfaces and integration power of the open source 
Eclipse platform 

► Web 2.0 and RESTful programming (this technology underpins the CICS 
Explorer concept) 

This IBM® Redbooks® publication shows how you can use the extensible design 
of CICS Explorer to complement the functionality already provided, with added 
functionality tailored to the needs of your business. We show you how to perform 
the following tasks: 

► Install the CICS plug-in SDK into your eclipse environment 

► Develop a simple plug-in for the CICS Explorer 

► Deploy the plug-in into CICS Explorer 

We provide several useful examples of plug-ins that we developed during the 
residency using the methodology we describe. 

The starting point for the book is that you already have CICS Explorer installed 
and configured with connectivity to your CICS region or CICSPlex®, and that you 
are looking for ways to customize CICS Explorer. 


The team who wrote this book 

This book was produced by a team of specialists from around the world working 
at the International Technical Support Organization (ITSO), Poughkeepsie 
Center. 

Chris Rayns is an IT Specialist and the CICS project leader at the ITSO, 
Poughkeepsie Center. He writes extensively on all areas of CICS. Before joining 
the ITSO, Chris worked in IBM Global Services in the United Kingdom as a CICS 
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Part 1 


Introduction 


In part 1 we review the evolution of CICS management before taking a look at the 
new CICS Explorer. We provide an overview of CICS Explorer and Eclipse. 
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CICS Evolution 


In this chapter we begin by taking a sideways look at the history of CICS System 
Management, and the benefits that CICS Explorer brings to the CICS systems 
management world. To develop new extensions to CICS Explorer, you need 
understanding of how Eclipse presents information, and how CICS Explorer uses 
the facilities that Eclipse provides. We therefore take a high-level overview of the 
external aspects of CICS Explorer and Eclipse that you need to understand to 
write your own CICS Explorer plug-ins. 
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1.1 Evolution of CICS system management 

CICS Explorer is the latest significant evolution in the management and analysis 
of your CICS environment, but CICS has a long history of building on, and 
improving its system management tools. 

CICS is now over 40 years old. Over the years, there have been significant 
changes in the way in which CICS is managed. Here are several of the important 
milestones in the evolution of CICS systems management. 

1 .1 .1 The dark ages: CSMT and Assembler macros 

When CICS first appeared, there were no nice graphical interfaces. CSMT is the 
CICS transaction that was executed on these prehistoric devices. In these early 
days there was no such thing as "CEMT PERF SHUT". It was CSMT you used to 
close down your CICS region. If you try to run CSMT on your brand new CICSTS 
4.1 region, it tells you that it is not defined. Dig around in the CICS-supplied CSD 
definition and you will find it. Today, the only thing that remains of transaction 
CSMT is the transient data queue to which many CICS messages are still routed. 

As far as defining new CICS resources such as files, transactions, and programs, 
look no further than a set of CICS resource tables coded using Assembler 
macros. If you needed to install a new terminal, program, or transaction, you 
needed to restart your CICS. 

1.1.2 The middle ages: CEMT and the first GUI 

With the advent of 3270 green panel devices, we had the ability to format entire 
displays of data, and a new state of the art, full panel CICS management tool 
was born. CEMT arrived, with its state of the art graphics interface (See 
Figure 1-1 on page 5). With CEMT, the systems programmer can see the state of 
the CICS region, and the resources installed in that region. 
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1 INQUIRE SYSTEM 


STATUS: RESULTS - OVERTYPE TO MODIFY 

Agi ng( 00500 ) 

Progautoexit( DFHPGADX ) 

Akp( 02000 ) 

Progautoinst( Autoactive ) 

Cicstslevel (030100) 

Reentprotect (Reentprot) 

Cmdprotect (Nocmdprot) 

Release(0640) 

Db2conn(DB2C0NN) 

Runaway ( 0020000 ) 

Debugtool ( Nodebug ) 

Scandelay( 0100 ) 

Dfl tuser(HAIMO) 

Sdtran(CESD) 

Dsal imit( 05242880 ) 

Sosstatus(Notsos) 

Dsrtprogram( NONE ) 

Storeprotect (Active) 

Dtrprogram( DFHDYP ) 

Time( 0001000 ) 

Dumping ( Sysdump ) 

Edsal imit( 0524288000 ) 
Forceqr( Noforce ) 
Logdefer( 00005 ) 

Maxtasks( 200 ) 

Mrobatch( 001 ) 

Oslevel (010900) 
Progautoctlg( Ctlgmodify ) 

APPLID=SCSCERW1 

Tranisolate(Inactive) 

SYSID=ERW1 

RESPONSE: NORMAL 
DATE: 02.03.10 

TIME: 11.06.19 

PF 1 HELP 3 END 

SF 

5 VAR 7 SBH 8 SFH 9 MSG 10 SB 11 


Figure 1-1 Graphics interface 


1.1.3 The renaissance: CEDA and CICS System Definition 

CEMT was a great tool, but we were still obliged to assemble and compile our 
DFHPCT, DFHPPT, DFHFCT, and DFHTCT macros (to mention but a few) to 
modify or install new resources into our CICS region. The next great leap forward 
in CICS systems management was the CICS System Definition (CSD) and a new 
CICS-supplied transaction CEDA. Now we can add new files, programs, 
transactions, and terminals to our CICS region with a few keystrokes, and without 
having to stop and restart our CICS region. 
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1.1.4 The enlightenment: CICSPlex SM 


CEDA and CEMT made the job of the CICS system programmer easier, but as the 
size of customer CICS installations grew, it became evident that a new approach 
was needed. To execute CEDA or CEMT in each of tens or hundreds of CICS 
regions was a logistical nightmare. The introduction of CICSPlex SM, with its new 
APIs and system management tools, allowed system administrators to group 
together CICS regions according to their particular requirements, and manage those 
groups of CICS regions as single entities, installing, controlling, and monitoring 
those CICS regions without the need to log on to each CICS region simultaneously. 

CICSPlex SM used the advanced features of the latest 3270 terminal technology to 
bring a rich user interface to the management of complex CICS environments. With 
the advent of the Internet and the Web, the 3270 CICSPlex SM interface has been 
superseded by a Web Browser interface called the Web User Interface. Figure 1-2 
shows a CICSPlex SM WUI screen showing CICS regions on MVS image SC66. 



Figure 1-2 CICSPlex SM WUI panel 
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Although the face of CICSPlex SM changed with the advent of the WUI, the 
underlying philosophy of CICSPlex SM is probably more important today than 
when it was first conceived. It remains a key element in the management of 
CICSPlexes big and small across the world. We see that CICS Explorer relies on 
CICSPlex SM to provide it with timely and accurate information about the state of 
the CICS resources it manages. 

1.1.5 The baby boom: The CICS Tools Suite 

In recent years, the CICS tools toolset has significantly improved the facilities at 
the disposal of the CICS System Administrator, allowing them to simplify the 
management and monitoring of their CICS real estate, and giving them the ability 
to extract the underlying structure of their CICS applications even though the 
programmers, the documentation, and sometimes the source code, of those 
applications are long gone. CICS configuration manager took the best of CEDA 
and CICSPlex SM resource management and created something simpler and 
easier. CICS interdependencies analyzer allowed administrators to understand 
the implications of proposed changes to their application suites. CICS 
Performance Analyzer gave new insight into the performance of those 
applications. However, each of the tools had its own user interface, its own set of 
panels. CICS Explorer brings a common user interface and user experience to 
the whole CICS toolset in a single (free) product. Do not forget the Tivoli® 
Omegamon family of products, which also contain a rich set of functions for the 
management of CICS resources. 


1.1.6 The brave new world: CICS Explorer 

All the systems management tools described previously have their own separate 
user interfaces - CICS 3270 transactions, Web browser, TSO ISPF panels, batch 
jobs. When you consider that there is also a whole host of third-party, vendor, or 
customer home-grown CICS systems management tools, each with their own 
user interface and implementation, you can see why CICS system administrators 
and programmers tend to regard with suspicion yet another tool with yet another 
user interface to learn. 

CICS Explorer signals an end to this confusion. It allows all the tools and 
applications that a user needs to perform a business task to present the same 
structure and user interface. Tools that are built by IBM, vendors, and customers 
extend and enhance CICS Explorer in a consistent way, adding value to CICS 
management without the need to reinvent or redefine CICS Explorer's user 
interface. 
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CICS Explorer has achieved this by embracing the Eclipse open source 
community's extensible development platform, runtimes, and application 
frameworks for building, deploying, and managing software. 


1 .2 Overview of CICS Explorer 

It is worth spending a little time looking at the Eclipse user interfaces, and how 
they are used by CICS Explorer. The better you understand these interfaces, the 
easier it is for you to create useful new CICS Explorer plug-ins. 


Note: To learn in detail about CICS Explorer and how you can use and 
customize it without the need for programming, see IBM Redbooks publication 
CICS Explorer, SG24-7778. 


The intention here is to focus on the elements and concepts of Eclipse, which are 
going to be interesting from a plug-in programming point of view. We can break 
the Eclipse display down into a number of constituent parts. 


1 .2.1 Workbenches and Perspectives 

When you start your CICS Explorer for the first time, you are presented with the 
the CICS Explorer Workbench, shown in Figure 1-3 on page 9. 
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Each Workbench window contains one or more perspectives. In Figure 1-3, we 
see the default perspective for the CICS Explorer, provided by the CICS Explorer. 
Think of an Eclipse Perspective as being a set of related tools grouped together 
for a specific task or role. For example, the perspective used by a CICS Systems 
Programmer is different from that used by a COBOL Application Developer, a 
Java Application Developer, or a Web designer. 

If you click Window Open Perspective -> Other you can see the list of 
perspectives supplied with this version of CICS Explorer. The Resource 
perspective is also provided by CICS Explorer. All the other perspectives you see 
come with Eclipse RCP. In this book we look at and mostly work with the CICS 
SM perspective. The Resource perspective is used to create and manage CICS 
Event bindings and objects. Perspectives are a powerful way of creating displays 
that are customized to show the tasks and information required for a specific job 
or role (with no need for programming). 


Chapter 1 . CICS Evolution 9 


1.2.2 Views 


Think of views as the primary Eclipse interface for displaying the information you 
want to see. A perspective can be made up of many views, or of a single view. 


Tip: If you are in a perspective with multiple views, and you want to 
concentrate on a single view, double-click that view to get it in full-panel mode. 
After you have finished, double-click its tab again, and you return to the 
original perspective. 


Views can occur singly, or in what is called a tab group, or tabbed notebook. For 
example, if you look at the default CICS SM perspective, you can see that the 
welcome view is on the right hand side on its own. On the left, you can see that 
there is a tab group made up of the CICSPlex Explorer and CICSPlex Repository 
views. In the center, there is another tab group, which contains views for CICS 
resources managed by CICS Explorer. Add a new view of another CICS resource 
to the central tabbed notebook by simply clicking (for example) Operations -»■ 
Web Services. 

If you click the CICS regions listed in the CICSPlex Explorer view, the resources 
displayed in the upper central tab group are changed to reflect that you are now 
viewing the data associated with that region. 

As a general rule, when using Eclipse, the left tab group to navigate around the 
information available in the workspace, and the information you are interested 
appears in the lower central tab group. This is a general rule that applies to most 
Eclipse RCP implementations. Similarly, there is usually a tab group in the lower 
central portion of the workspace, which tends to be used to signal problems, 
errors, or (in the case of our CICS SM view) events that might present a potential 
problem. The default view in this panel is for CICSPlex SM alerts. If one of our 
CICS Regions raises an alert (for example, goes short on storage, or reaches 
maxtask), the appropriate alert is displayed in this view. 
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Each view can have a menu of related actions or views associated with it. You 
display this menu by right-clicking the view tab (see Figure 1-4). 
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Figure 1-4 View tab menu 


The actions we see in the Tasks view are the defaults provided by Eclipse. There 
are no CICS-specific ones unless we choose to add a plug-in that adds an action 
we want to implement. 
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1.2.3 Menus and the menu bar 


Each perspective has a menu bar, which has been designed and customized to 
detail a menu of actions or views that are related to a specific menu item. So, for 
example, the menu bar of the CICS SM perspective looks like Figure 1-5. 



Figure 1-5 CICS SM perspective menu bar 

As you click each item in the menu bar, a list of actions or views associated with 
that item is presented, and you can select the one you want. You can see that 
several of the menu items, such as File, or Edit are standard Eclipse user 
interface menu items, but others, such as WLM, RTA, Operations, are provided 
by plug-ins provided by CICS Explorer. If you want to add new menus that are 
appropriate to your installation, write a plug-in to do it. Later we show how you 
can create your own menus that you can add to a new or existing perspective’s 
menu bar. 
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1.2.4 Toolbars 


A toolbar is a collection of graphical icons that when clicked, typically execute a 
wizard associated with the task represented by the icon, or when right-clicked, 
display a menu of actions or views associated with that icon. 

There are five separate kinds of toolbars in Eclipse, so when writing a new 
plug-in for a new tool, you need to give thought to the best place to invoke that 
new plug-in. Figure 1-6 shows the kinds of toolbars in Eclipse. 



Figure 1-6 Eclipse toolbars 


The main toolbar (sometimes called the workspace toolbar) is associated with 
the perspective. By default, when you define a new item on the menu bar (called 
an action set, the Eclipse SDK generates a corresponding icon on the toolbar to 
graphically represent the item. 

A new plug-in that defines an action or view associated to a particular view can 
be defined to be displayed in a view toolbar. 
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The perspective switcher is a tool that allows you to move quickly from one 
perspective to another, with each open perspective represented by an icon. 

To get instant access to your most commonly used views, add them to the fast 
view toolbar by right-clicking the View tab and selecting Fast View. 

1.2.5 Editors 

When you want to define or modify Eclipse resources, depending on the 
resource, Eclipse opens an appropriate editor in the Editor Area (usually the 
center panel in the workspace). If the Eclipse resource is a plain text file, it is an 
editor that works with plain text. If it is an XML file, Eclipse contains an editor with 
functionality for working with XML data (such as syntax checking). As you 
develop new plug-ins, you might need to invoke an editor. 

In the case of the CICS Explorer, the CICS Explorer has a specific editors for 
working with CICS resources. If you double-click a CICS resource (for example a 
CICS region), CICS Explorer opens an editor session to the right of the current 
view, showing the attributes for that resource. This is shown in Figure 1-7. 



Figure 1-7 Double-click region object to invoke CICS Editor to display attributes 
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1.2.6 Wizards 


When you choose to create or modify a CICS resource, a wizard opens in a 
separate pane, to the right of the tabular views. The wizard guides you through 
the creation of the new resource, prompting you for the correct information. 

For example, if you want to create a new Program definition for a CICS region, 
you can right-click that region, and select New ->• Program Definition and a 
wizard opens to allow you to provide the necessary information. See Figure 1-8. 
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Figure 1-8 CICS Explorer CICS Resource Editor 


There might be scenarios where you want to do something similar for your own 
business needs, and you can do this by writing your own plug-in. 
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1.3 Overview of Eclipse 


Because CICS Explorer is based on Eclipse, it is important to have idea of the 
relationship between the two. In this section we take a high-level view of aspects 
of Eclipse of which we need to be aware. 

The Eclipse community has several separate ongoing focuses of activity. The 
one on which CICS Explorer is based is called Eclipse Rich Client Platform 
(RCP). 

A rich client is a fat client. That means we have a fat, rich client. That is to say, it 
is an application that uses the windowing and GUI features of the operating 
system (for example, native widgets, drag and drop) and is integrated with the 
operating system’s component model (for example, ActiveX). This is what we are 
going to focus on. 

Figure 1-9 is a description of Eclipse RCP taken from the following Web page: 
http://www.ecl ipse.org/downl oads/download.php?file=/technology/phoenix/ 
tal ks/What-is-Ecl ipse-and-Ecl ipse-RCP-3.2.6.ppt 
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Native look and feel 

Window management 
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First-class development tools 
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Allows programmers to focus on core application not the plumbing 

Don't reinvent the wheel 


Figure 1-9 Eclipse description 
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Sounds like a good fit with the aims of CICS Explorer? That is what the CICS 
development organization thought. Eclipse RCP provides a set of base functions 
and services that handle, among other things, user interfaces, help panels, and 
update management, as shown in Figure 1-10. 



Figure 1-10 Eclipse RCP structure 
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The base functions provided by Eclipse RCP are designed to be extensible, and 
available for use by new components (plug-ins) that implement functionality 
specific to a particular technical or business need. The plug-in developers use 
the provided interfaces to write their own components, which can provide 
functionality used by other plug-ins, as shown in Figure 1-11. 



Figure 1-11 Eclipse RCP component model 


To summarize, Eclipse RCP is a runtime environment providing a set of 
commonly used services for use by components (plug-ins) developed to run 
inside that runtime environment (sound familiar?). 
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Where it is necessary to connect to a remote system to retrieve information, a 
plug-in can use the communications facilities provided by Eclipse, or implement 
its own communication services. This might be made available to other plug-ins, 
as shown in Figure 1-12. 



Figure 1-12 Eclipse RCP Connectivity 

As we see in more detail later, CICS Explorer uses the communications facilities 
provided by Eclipse RCP to connect to CICS TS to retrieve and modify the data it 
uses. The list of protocols to be used is not exclusive, you simply write a plug-in 
to implement the transport protocol you need to use. 

As well as the Eclipse RCP run-time itself, Eclipse provides a development 
environment specifically for plug-in development. This development environment 
is called the Eclipse plug-in SDK. It is also referred to as a Plug-in Development 
Environment (PDE). We are using the Eclipse plug-in SDK to develop and test 
our CICS Explorer plug-ins in this Redbooks publication. 
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When developing Eclipse plug-ins, it is important to remember that you usually 
deal with two separate Eclipse environments: 

► The Eclipse plug-in SDK, where you develop and test your plug-in (it contains 
a runtime environment to allow you to test). 

► The target Eclipse environment, where you deploy the finished (and tested) 
Eclipse RCP application. In our case the target environment is the CICS 
Explorer runtime. 

As a general rule, the default active view (the one you can see) on the left 
contains a list of resources related to the perspective we are using. In this case, 
the default view shown in pane 1 is a list of the plug-in projects that exist in the 
Eclipse workspace in which you are working. Because you have not yet created 
any plug-ins, the pane is blank. However, if we click the Plug-ins tab, to bring that 
view to the front, we can see all the plug-ins that come with the Eclipse SDK. 

When working with the CICS Explorer, it is important to remember that it is still a 
work in progress. However, it is seen by the CICS development organization as a 
critical element in the future of CICS. The plan is to roll out new versions of CICS 
Explorer, with new functionality, several times per year. 

We have already seen significant progress since the CICS Explorer first 
appeared. In its original form, CICS Explorer is not able to update CICS 
resources, only to view them. New in CICS TS version 4 was the ability to modify 
and create CICS resources. Originally, you could only connect to a CICSPlex SM 
WUI CICS region, but you can now connect to a single standalone CICS region. 

We see in the course of this book that there is already a rich set of functions in 
CICS Explorer, which are there to be used in new and innovative ways. We hope 
that after you have read this book, and tried the samples, you will share your 
ideas for new ways to use CICS Explorer with the wider CICS community through 
the CICS Explorer forum at the following Web page: 
http://www.developerworks/forums/forum.jspa?forumID=1475 

If you have any questions about CICS Explorer, or about the topics discussed in 
this book, you can post them on the forum. 
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Part 2 


Exploring CICS 
Explorer 


In this part of this Redbooks publication we show how CICS Explorer uses the 
CICS Client Management Interface (CMCI). CMCI is the strategic interface for 
CICS Explorer communications with CICS TS. We also we take an in depth look 
at the CICS Explorer SDK. 


© Copyright IBM Corp. 2010. All rights reserved. 
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CICS Explorer and the CICS 
Client Management Interface 


In this chapter we take a more detailed look at the way CICS Explorer uses the 
CICS Client Management Interface (CMCI). CMCI is the strategic interface for 
CICS Explorer communications with CICS TS. 

If you are simply using CICS Explorer as a user, the way CICS Explorer uses 
CMCI is transparent to you. 

If you plan to write additional functions to run inside CICS Explorer, you need to 
understand how CICS Explorer uses the CMCI to create efficient new CICS 
Explorer plug-ins, how it communicates with CICS, how it stores information 
about the CICS environment, and how it is possible to manipulate the data that 
CICS Explorer uses. 


Note: CICS Explorer initially used a separate (non-RESTful) implementation 
of HTTP to communicate with a CICS WUI region over TCP/IP, but CMCI is 
the strategic interface, so it is what we focus on here. 


We also compare the CICS Explorer with the Web user interface to understand 
how they differ, and why CICS Explorer is considered to be a better solution. 
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2.1 CMCI 


CMCI allows anyone to develop HTTP client applications that manage, install, 
and define CICS resources. CMCI is a simple but extremely powerful tool. The 
biggest user of the CMCI today is CICS Explorer. 

CMCI is CICSPlex SM code. It runs either in a CICSPlex SM WUI server, or in a 
stand-alone CICS region (in which case it is known as Systems Management 
Single Server [SMSS]). Like CICS Explorer and CICSplex SM, you can divide 
CICS Explorer activities into two categories: 

► Operational activities 

Enabling, disabling, or modifying installed resources, or system settings 
(analogous to CEMT). 

► Administration activities 

Defining, installing, modifying or deleting CICS resources (analogous to 
CEDA or CICSPlex SM’s Business Application Services (BAS)). When used 
in CICSPlex mode CMCI works with CICS resources managed by BAS; when 
used in a single standalone region it works with the CICS CSD. The 
repository used for the resources being managed is completely transparent to 
the user. 

For a detailed description of the CMCI implementation and the API, enter the 

search argument “CMCI” at the following Web page: 

http ://publ ib.boulder.ibm.com/infocenter/cicsts/v4rl/index. jsp 


2.1.1 CMCI is a RESTful implementation 

CMCI is a new system management API, based on Representational State 
Transfer (RESTful) principles. The speed and flexibility of CICS Explorer are 
derived largely from CMCI’s RESTful implementation. A RESTful application 
makes use of the following methods (as defined in the HTTP Protocol) to define 
actions that can be performed (in the case of CMCI, on a CICS resource): 

► POST 

Create resources on the data repository. 

► GET 

Retrieve information about resources. 

► PUT 

Update existing resources in the data repository, set attributes, or perform 
actions on installed resources. 
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► DELETE 


Remove resources from the data repository or discard installed resources. 

The key factor in a RESTful implementation is efficient use of the HTTP methods, 
URI strings, and query strings. 


Note: REST stands for Representational State Transfer. This is not the most 
informative acronym, and this book is not the place for a lengthy discussion of 
REST. For the official description, and useful background, try the following 
Web pages: 

► http://www.ics.uci .edu/~fielding/pubs/dissertation/top.htm 

► http://www.ibm.eom/developerworks/web/l ibrary/wa-ajaxarch/ 

► http://www.surfscranton.com/architecture 

► http://rest.bl ueoxen.net/cgi-bin/wi ki .pi TwhatlsREST 


2.1.2 CMCI and CICSPlex SM resource tables 

Almost all CICS and CICSPlex SM resources that are managed by CICSPlex SM 
are described and managed by means of a set of resource tables. CMCI uses 
these resource tables. The CICSPlex SM resource table architecture has been 
extended to allow it to work with the CMCI’s RESTful approach: 

► Each resource type now has a new external resource name section. This 
external name is the one specified by the CMCI client to select that resource 
type. For example, the LOCFILE CICSPlex SM resource type (local VSAM 
file) is defined with an external resource name of CICSLocalFile. 

► Each resource type now has a valid CICS Management Client Interface HTTP 
methods section, which defines the HTTP methods valid for the resource. 

► The error codes returned by CICSPlex SM when accessing resource tables 
have been re-ordered to make things simpler for CMCI users 
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2.2 CMCI caching 


CMCI uses caching technology to provide faster access to data and reduce the 
bandwidth and network latency associated with CMCI requests. The CMCI client 
(CICS Explorer in our case) chooses to use this caching by specifying the 
NODISCARD=NODISCARD parameter on the query string, which it uses to 
articulate its CMCI request to CMCI. Read the sections that follow, which provide 
examples of CMCI flows, and accessing the cache, to see how it is used. The 
default behavior of CICS Explorer is to use caching. 


Note: Cached results are stored in the CICS WUI region in its above the bar 
domain storage pool WU_64, so make sure you set MEMLIMIT and the EDSA 
limit carefully 


Use both indexing and ranges to target your requests for cached data. For 
example, to show the first five resource records from a previously created cache, 
starting at record nine, the URI query string looks like this: 

. ./CICSResul tCache/C46DB57FAE2D8F64/9/5?N0DISCARD 

Where the string C46DB57FAE2D8F64 identifies a cache created earlier (see 
the examples of the flows for separate activities). 

You can also use the range value when creating the cache, to limit the cache to 
the first ten records. The URI you submit looks like this: 

/CICSSystemManagement/CICSProgram/EPRED///10?N0DISCARD=N0DISCARD&SUMM0NLY 

2.2.1 Defining a CICS resource definition with the CMCI 

The resource upon which the action is to be performed is specified in the URI of 
the HTTP request received by CMCI. So for example, if we look at the creation of 
a URIMAP, with name MYURI, in BAS, we see the request flow in from CICS 
Explorer over the CMCI, as shown in Example 2-1 . 

Example 2- 1 HTTP request for to define a CICS resource using CMCI 

POST /CICSSystemManagement/CICSDefi ni tionURIMap/EPRED HTTP/1.1 
Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: wtsc66.itso.ibm.com:16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 

Content-type: appl ication/x-www-form-url encoded 
Content-Length: 141 
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<request> 

<create> 

Ottributes USAGE="PIPELINE" PIPELINE="MYPIPE" PATH="/path" 
H0ST="host. ibm.com" NAME="MYURI" DEFVER="l"/> 

</create> 

</request> 


Because we are creating a URIMAP resource, we use the HTTP verb POST. The 
resource we are working with is a URIMAP definition so the URI specifies: 
/CICSSystemManagement/CICSDefi ni ti onURIMAP/EPRED 

The EPRED at the end of the URI specifies the CICSPlex SM context (in our 
case this resource is associated with the EPRED CICSplex). The body of the 
HTTP request contains the XML data providing the attributes of the object we 
want to create. 

If we look at the HTTP response to our create request returned by the CICS WUI 
region we see the information shown in Example 2-2. 

Example 2-2 CMC I HTTP Response for defining a URIMAP 

HTTP/1.1 200 OK. .Cache-Control : no-store 
Date: Wed, 14 Oct 2009 12:53:40 GMT 
Server: IBM_CICS_Transaction_Server/4. 1.0(z0S) 

Content-Type: application/xml; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 

147 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema-instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http://wtsc66.itso.ibm.com: 16001/CICSSystemManagement/schema/CICSSystem 
Management. xsd" 

version="1.0" 

connect_version="0410"> 

<resul tsummary 

api_responsel="1024" 
api_response2="0" 
api_responsel_al t="0K" 
api_response2_alt=" " 
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recordcount="l" 
displayed_recordcount="l" /> 

<records> 

2A4 

<cicsdefinitionurimap _keydata="D4E8E4D9C9404040014040404040404040" 
analyzer="NO" atomservice="" authenticate="NO" 
certificate^' " 

changeagent="DREPAPI" changeagrel ="0660" 
changetime="2009-10-14T08:53:40" 

changeusrid="CICSRSl" characterset="" ciphers="" 

converter=" " 


createtime="2009-10-14T08:53:40" csdgroup="" 
defver="l" desccodepage="37" 

description^" 1 hfsfile="" host="host. ibm.com" 

hostcodepage=" " 


location="" mediatype="" name="MYURI" 
path="/path" pipel ine="MYPIPE" 


port="N0" program="" redi recttype="NONE" 
scheme="HTTP" status="ENABLED" 

tcpipservice="" tempi atename="" transaction="" 

usage="PIPELINE" 


userdatal="" userdata2="" userdata3="" userid="" 


webservice="" /> 
D 

</records> 


B 

</response>. . 


We can see that the XML schemas for the CICS XML data are specified on the 
response tag, and can be retrieved for the CICS WUI region if required. 

The attributes of the resul tsummary tag show us whether our create was 
successful or not. api_responsel="1024" means the operation was successful. 
api_responsel_alt="OK" is the response code in human-readable form. The 
number of new CICS Definition records created is also returned (recordcount=l). 

The record element gives us the details of all the new resources created. Each 
record’s first attribute is _keydata. This is a value that uniquely identifies this 
record. It is also used to link records to feedback. In our case, we have a 
ci csdef i ni ti onurimap with all the attributes of our newly created URIMAP. The 
records element provides a fully externalized interpretation of almost all CICS 
resources and their attributes. 
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Note: If you look at a CICS trace of the CMCI flows, you see that the various 
parts of both the HTTP request and the HTTP response are split across a 
number of Sockets domain SEND and RECEIVE calls. 


2.2.2 Viewing a CICS resource definition using CMCI 

The HTTP verb used for inquiring on a resource is GET As with all CMCI calls, 
the resource upon which the action is to be performed is specified in the URI of 
the HTTP request received by CMCI. See Example 2-3. 

Example 2-3 Get request for CMCI view 
GET 

/CICSSystemManagement/CICSDefi ni tionURIMap/EPRED?NODISCARD=NODISCARD&SUMMONLY&C 
RITERI A= ( (NAME= ' MYURI 1 ) ) HTTP/1 . 1 
Authorization: Basic Q01DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: local host: 16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 


We see in Example 2-3 that the URI identifies the type of resource. The query 
String NODISCARD=NODISCARD&SUMMONLY&CRITERIA= ( (NAME= 1 MYURI 1 ) ) identifies the 
name of the resource we want to access (MYURI), and that we only want a 
summary of its associated data. The NODISCARD name/value pair tells CMCI to 
cache the information we are retrieving. The default behaviour of Explore is to 
always request that retrieve data be cached by CMCI. If we look at the HTTP 
response returned by CMCI (Example 2-4), we see that the inquire was 
successful, but that CMCI has not returned the data for the inquire; instead it has 
returned a cachetoken which can be saved and used to request information 
about this and perhaps other URIMAPs. 

Example 2-4 HTTP response returned by CMCI 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:20 GMT 

Server: IBM_CICS_Transaction_Server/4.1.0(z0S) 

Content-Type: application/xml ; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 

<?xml version="1.0"?> 

<response xml ns=" http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi=" http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http://www.ibm.com/xmlns/prod/CICS/smw2int 
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http: //local host:16001/CICSSystemManagement/schema/CICSSystemManagement.xsd" 
versi on=" 1.0" connect_versi on="0410"> 

<resultsummary api_responsel="1024" api_response2="0" 
api_responsel_alt="OK" api_response2_al t="" recordcount="l" 
cachetoken="C4EF7130DF20DC09" />B 
</response> 


To get the details about our URIMAP CICS Explorer now issues a second GET 
HTTP request. This time the URI references the cached data identified by the 
cachetoken received earlier: 

/CICSSystemManagement/CICSResul tCache/C4EF7130DF20DC09/l/l 

Note that the cachetoken is suffixed by /l/l. This tells CMCI to return only one 
record starting at record one. See Example 2-5. 

Example 2-5 CMCI cached data HTTP GET request 

GET ?N0DISCARD=N0DISCARD HTTP/1.1 
Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: I BMCI CS_CI CS Explorer/1.0.2.200909240951 (Windows XP) 
Host: localhost:16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 


This time the HTTP response contains the data we are looking for (Example 2-6). 

Example 2-6 HTTP response to CICS Explorer inquire on URIMAP definition 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:20 GMT 

Server: IBM_CICS_Transaction_Server/4. 1.0(z0S) 

Content-Type: appl ication/xml ; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 
13D 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host : 16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

AF 
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<resul tsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="OK" api_response2_alt="" recordcount="l" 
displayed_recordcount="l" cachetoken="C4EF7130DF20DC09" /> 

C 

<records> 

2A4 

<cicsdefinitionurimap 

_keydata="D4E8E4D9C94040400 14040404040404040" analyzer="N0" 
atomservice="" authenticate="NO" certificate="" changeagent="DREPAPI" 
changeagrel="0660" changetime="2009-10-14Tll:26: 19" 
changeusrid="CICSRSl" characterset="" ciphers="" converter="" 
createtime="2009-10-14Tll:26:19" csdgroup="" defver="l" 
desccodepage="37" description="" hfsfile="" host="host. ibm.com" 
hostcodepage="" location="" mediatype="" name="MYURI" path="/path" 
pipeline="MYPIPE" port="N0" program="" redi recttype="N0NE" 
scheme="HTTP" status="ENABLED" tcpi pservi ce="" tempi atename="" 
transaction="" usage="PIPELINE" userdatal="" userdata2="" userdata3="" 
userid="" webservice="" /> 

D 

</records> 

B 

</response> 


2.2.3 Altering a URIMAP resource definition using CMCI 

To request CMCI to alter a resource definition, we use the PUT method on our 
HTTP request. The URI identifies the resource to be updated as a resource 
definition URIMAP (CICSDefinitionURIMap) in CICSPlex EPRED. The query 
string identifies the resource to be altered as MYURI. See Example 2-7. 

Example 2-7 HTTP request to CMCI to alter a CICS resource definition 
PUT 

/CICSSystemManagement/CICSDef i ni ti onURIMap/EPRED//?CRITERIA= ( (NAME= 1 MYU 
RI 1 )%20AND%20(DEFVER= 1 1 ' ) ) HTTP/1 . 1 
Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: localhost:16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 
Content-Length: 76 
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<request><update><attributes DESCRI PTION= " Hel 1 o World" 
/></update></request> 


The body of the HTTP request contains the XML message that details the 
change to be made to URIMAP. It is an update request to change the 
DESCRIPTION attribute of our URIMAP to Hello World. We can see the HTTP 
response sent on successful completion of the alter in Example 2-8 on page 32 
with the good return code in the resultset element, and the updated description 
attribute of the cicsdefinitionurimap element. 

Example 2-8 HTTP response from CMCI for an alter to a CICS resource definition 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:20 GMT 

Server: IBM_CICS_Transaction_Server/4. 1.0(z0S) 

Content-Type: application/xml; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 

13D 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host:16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

91 

<resul tsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="0K" api_response2_alt="" recordcount="l" 
displayed_recordcount="l" /> 

C 

<records> 

2AF 

<cicsdefinitionurimap 

_keydata="D4E8E4D9C94040400 14040404040404040" analyzer="N0" 
atomservice="" authenticate="N0" certificate^'" changeagent="DREPAPI" 
changeagrel="0660" changetime="2009-10-14Tll:26:20" 
changeusrid="CICSRSl" characterset="" ciphers="" converter="" 
createtime="2009-10-14Tll:26:19" csdgroup="" defver="l" 
desccodepage="37" description="Hel lo World" hfsfile="" 
host="host. ibm.com" hostcodepage=" " location="" mediatype="" 
name="MYURI" path="/path" pipel ine="MYPIPE" port="N0" program="" 
redirecttype="N0NE" scheme="HTTP" status="ENABLED" tepi pservi ce=" " 
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tempi atename="" transaction^" 1 usage="PIPELINE" userdatal="" 
userdata2="" userdata3="" userid="" webservice="" /> 

D 

</records> 

B 

</response> 


2.2.4 Installing a CICS resource definition using CMCI 

The HTTP method used to install a CICS resource definition is PUT. See 
Example 2-9. 

Example 2-9 HTTP Put request for CMCI Install 
PUT 

/CICSSystemManagement/CICSDefi ni tionURIMap/EPRED/?CRITERIA=( (NAME= 'MYURI 1 )%20AN 

D%20(DEFVER= 1 1 1 )) HTTP/1.1 

Authorization: Basic Q01DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: local host: 16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 
Content-Length: 131 

<request> 

<action name=" INSTALL"> 

<parameter name="USAGE" val ue="L0CAL"/> 

<parameter name="TARGET" val ue="EPRED4"/> 

</action> 

</request> 


The URI identifies: 

► The kind of resource we want to work with: CICSDefinitionURIMAP 

► The CICSPlex context EPRED . 

The query string identifies the resource we want to install: 

CRITERIA= ( (NAME= 'MYURI ' )%20AND%20(DEFVER= 1 1 1 )) . 

The body of the HTTP request contains an XML message with more detail about 
the operation to be performed. The action to be performed is an install, and the 
target region for the install is CICS region EPRED4. 
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If the install for a resource is successful, CMCI returns the HTTP response 
shown in Example 2-10. We can see from the api_responsel attribute of the 
resultset element that the operation completed normally. The details of the 
requested resource MYURI are returned in the records element. 

Example 2-10 HTTP Response for CMCI Isntall 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:21 GMT 

Server: IBM_CICS_Transaction_Server/4. 1.0(z0S) 

Content-Type: appl ication/xml ; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 

13D 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host:16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

91 

<resul tsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="0K" api_response2_alt="" recordcount="l" 
displayed_recordcount="l" /> 

C 

<records> 

2AF 

<cicsdefinitionurimap 

_keydata="D4E8E4D9C94040400 14040404040404040" analyzer="N0" 
atomservice="" authenticate="N0" certificate^'" changeagent="DREPAPI" 
changeagrel="0660" changetime="2009-10-14Tll:26:20" 
changeusrid="CICSRSl" characterset="" ciphers="" converter="" 
createtime="2009-10-14Tll:26:19" csdgroup="" defver="l" 
desccodepage="37" description="Hel lo World" hfsfile="" 
host="host. ibm.com" hostcodepage=" " location="" mediatype="" 
name="MYURI" path="/path" pipel ine="MYPIPE" port="N0" program="" 
redirecttype="N0NE" scheme="HTTP" status="ENABLED" tepi pservi ce=" " 
tempi atename="" transaction="" usage="PIPELINE" userdatal="" 
userdata2="" userdata3="" userid="" webservice="" /> 

D 

</records> 

B 

</response> 
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2.2.5 Inquiring on an installed CICS resource using CMCI 

As well as installing and updating CICS resource definitions (either in the CSD or 
in BAS), CMCI allows you to inquire on the operational status of resources that 
are already installed and in use. The HTTP request shown in Example 2-1 1 
shows an HTTP request sent by CICS Explorer to CMCI to inquire on the status 
of our installed URIMAP. You can see that the HTTP method specified is GET. As 
usual, the type of resource we are inquiring about is specified on the URI: 
/CICSSystemManagement/CICSURIMap/EPRED/EPRED4 

What do you notice about this URI compared to the one we have seen up until 
now? 

Example 2- 1 1 HTTP request to Inquire on ain installed CICS resource using CMCI 
GET 

/CICSSystemManagement/CICSURIMap/EPRED/EPRED4?N0DISCARD=N0DISCARD&SUMM0 
NLY&CRITERIA= ( (NAME= 1 MYURI ' )) HTTP/1 . 1 
Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: localhost:16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 


Because we are inquiring on an installed resource rather than a resource 
definition, the resource type is different from the one we have used in previous 
examples. We are dealing with a CICSURIMap. The context is still CICSPlex 
EPRED, but the scope of this request is to only target CICS Region EPRED4. 

Example 2-12 shows the HTTP response returned by CMCI to reply to our 
URIMAP inquiry. The body of the response shows that the operation was 
successful. The results of the inquiry have been cached, in the cache identified 
by the cachetoken attribute of the resultset attribute. 

Example 2-12 HTTP response with cachetoken for CMCI Inquire 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:35 GMT 

Server: IBM_CICS_Transaction_Server/4. l.O(zOS) 

Content-Type: appl ication/xml ; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 

13D 

<?xml version="1.0"?> 
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<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host:16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

95 

<resul tsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="OK" api_response2_alt="" recordcount="l" 
cachetoken="C4EF713F93BD0F82" /> 

B 

</response> 


To retrieve the actual data corresponding to the inquire, CICS Explorer sends a 
second HTTP request. The requested object type is CICSResultCache, and the 
URI also contains the cachetoken returned to CICS Explorer by CMCI, and the 
fact that CICS Explorer is only interested in one URIMAP, beginning at the first 
one. See Example 2-13. 

Example 2- 1 3 HTTP Get request for data for CMCI Inquire 
GET 

/CICSSystemManagement/CICSResul tCache/C4EF713F93BD0F82/l/l?N0DISCARD=N0 
DISCARD HTTP/1.1 

Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: localhost:16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 


This time the HTTP response contains the attributes of our installed URIMAP. 
See Example 2-14. 

Example 2-14 HTTP response with data for CMCI inquire 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:35 GMT 

Server: IBM_CICS_Transaction_Server/4. l.O(zOS) 

Content-Type: application/xml; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 

13D 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 
xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 
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xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host:16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

AF 

<resul tsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="OK" api_response2_alt="" recordcount="l" 
displayed_recordcount="l" cachetoken="C4EF713F93BD0F82" /> 

C 

<records> 

37A 

<ci csurimap _keydata="D4E8E4D9C9404040" analyzerstat="NOANALYZER" 
atomservice="" authenticate="NOAUTHENTIC" basdefi never="l" 
certificate="" changeagent="DREPAPI" changeagrel ="0660" 
changetime="2009-10-14Tll:26:20" changeusrid="CICSRSl" characterset="" 
ciphers="" converter="" definesource="CPSMV01" 
defi netime="2009-10-14Tll :26: 19" enabl estatus="ENABLED" 
eyu_cicsname="EPRED4" eyu_cicsrel="E660" eyu_reserved="0" hfsfile="" 
host="host. ibm.com" hostcodepage="" hosttype="NOTAPPLIC" 
i nstal 1 agent="CREATESPI" install time="2009-10-14Tll:26:21" 
instal 1 usrid="CICSRSl" i pf ami ly= "UNKNOWN" i presol ved= "0.0. 0.0" 
location="" maprefcount="0" matchdisabld="0" matchredi rec="0" 
mediatype="" name="MYURI" numci phers="0" path="/path" pi pel i ne="MYPIPE" 
port="-l" program="" redi recttype="NONE" scheme="HTTP" tcpipservice="" 
tempi atename="" transaction="CPIH" usage="PIPELINE" userid="" 
webservice="" /> 

</records> 

B 

</response> 


2.2.6 Modifying an installed CICS resource using CMCI 

To request CMCI to modify an installed resource, we use the PUT method on our 
HTTP request. The URI identifies the resource to be updated as an installed 
URIMAP (CICSURIMap) in region EPRED4 in CICSplex EPRED. See 
Example 2-15. 

Example 2-15 HTTP PUT request for a CMCI modification 
PUT 

/CICSSystemManagement/CICSURIMap/EPRED/EPRED4?CRITERIA= ( (NAME= 1 MYURI ' ) ) 
HTTP/1.1 

Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: localhost:16001 
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Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 
Content-Length: 51 

<request><action name="DISABLE"></action></request> 


The body of the HTTP request contains the XML message with the details of the 
update we want to perform, in this case DISABLE the URIMAP. Example 2-16 
shows the HTTP response returned by the CMCI. Note that the enablestatus 
attribute of the cicsurimap element is set to DISABLED. 

Example 2-16 HTTP response to CMCI disable request 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:36 GMT 

Server: IBM_CICS_Transaction_Server/4. l.O(zOS) 

Content-Type: appl ication/xml ; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 
13D 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host : 16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

91 

<resultsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="0K" api_response2_alt="" recordcount="l" 
displayed_recordcount="l" /> 

C 

<records> 

386 

<ci esurimap _keydata="D4E8E4D9C9404040" analyzerstat="NOANALYZER" 
atomservice="" authenticate="NOAUTHENTIC" basdefi never="l" 
certificate^'" changeagent="DREPAPI" changeagrel ="0660" 
changetime="2009-10-14Tll:26:20" changeusrid="CICSRSl" characterset="" 
ciphers="" converter="" definesource="CPSMV01" 
defi netime="2009-10-14Tll :26: 19" enabl estatus="DISABLED" 
eyu_cicsname="EPRED4" eyu_cicsrel="E660" eyu_reserved="0" hfsfile="" 
host="host. ibm.com" hostcodepage="" hosttype="NOTAPPLIC" 
instal lagent="CREATESPI" instal 1 time="2009-10-14Tll :26:21" 
instal 1 usrid="CICSRSl" i pf ami ly= "UNKNOWN" i presol ved= "0.0. 0.0" 
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location="Hel lo World" maprefcount="0" matchdisabld="0" 
matchredirec="0" mediatype="" name="MYURI" numci phers="0" path="/path" 
pipeline="MYPIPE" port="-l" program="" redi recttype="NONE" 
scheme="HTTP" tcpi pservi ce="" tempi atename="" transaction="CPIH" 
usage="PIPELINE" userid="" webservi ce="" /> 

D 

</records> 

B 

</response> 


2.2.7 Discarding an installed resource using CMCI 

In Example 2-17 we see the HTTP request sent to the CMCI by CICS Explorer 
when it wants to discard an installed CICS resource. Note that now we are using 
the DELETE method. The URI identifies the type of resource to be discarded, and 
which CICS region in which CICSPlex, whilst the query string gives the name of 
the resource to be discarded MYURI. 

Example 2- 1 7 HTTP request to CMCI discard an installed resource 
DELETE 

/CICSSystemManagement/CICSURIMap/EPRED/EPRED4/?CRITERIA=( (NAME= 1 MYURI 1 ) 
) HTTP/1.1 

Authorization: Basic Q01 DUlJTMTpibHUzQjBvaw== 

User-Agent: IBM_CICS_CICS Explorer/1.0.2.200909240951 (Windows XP) 

Host: localhost:16001 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive 
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When CICS has successfully discarded MYURI, it returns the HTTP response 
shown in Example 2-18, with api_responsel set to 1024. 

Example 2-18 HTTP Response from CMC I to a discard of an installed resource 

HTTP/1.1 200 OK 

Cache-Control : no-store 

Date: Wed, 14 Oct 2009 15:26:37 GMT 

Server: IBM_CICS_Transaction_Server/4. 1.0(z0S) 

Content-Type: appl ication/xml ; charset=UTF-8 
Transfer-Encoding: chunked 
Connection: Keep-Alive 
13D 

<?xml version="1.0"?> 

<response xml ns= "http://www.ibm.com/xmlns/prod/CICS/smw2int" 

xml ns :xsi = "http: //www. w3.org/2001/XMLSchema- instance" 

xsi :schemaLocation=" http: //www. ibm.com/xml ns/prod/CICS/smw2i nt 

http: //local host : 16001/CICSSystemManagement/schema/CICSSystemManagement 

.xsd" version="1.0" connect_version="0410"> 

88 

<resultsummary api_responsel="1024" api_response2="0" 
api_responsel_al t="0K" api_response2_alt="" recordcount="l" 
successcount="l" /> 

B 

</response> 


2.2.8 A fun way to explore the CMCI Interface 

If you want to learn about the CMCI and better understand the messages that 
flow between the client and CMCI, you can see some of it from a Web browser. 
Enter the following URL on a Web browser: 

http ://9. 12.4.75: 16001/CICSSystemManagement/CICSURIMap/EPRED/EPREDW//l? 
N0DISCARD=N0DISCARD&SUMM0NLY 

You see the XML response returned by the CMCI shown in Figure 2-1 . 
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Figure 2-1 Using a Web browser to drive the CMC I 


2.2.9 Comparing the Web user interface and CICS Explorer 

For a CICS person, probably the simplest way to appreciate the advantages of a 
RESTful style application when compared with a more traditional Web 
application is to compare the CICSPlex SM WUI with the CICS Explorer. They do 
much the same thing, but most users agree that the CICS Explorer is a far 
superior implementation. 


Chapter 2. CICS Explorer and the CICS Client Management Interface 41 


WUI Plumbing 

Figure 2-2 is an overview of how information about the CICSPlex is exchanged 
between the WUI and its HTTP client. 



Figure 2-2 Browser-based component architecture 


The workstation element of the WUI is a Web browser (an HTTP client), that is, 
Internet CICS Explorer, or Mozilla Firefox, or something similar. It is a thin client, 
with almost no client-side programming logic other than Javascript to help with 
formatting of the HTML data being passed from the CICS WUI region to the 
browser. All the information about the CICS resources and the logic to manage 
that information being passed to the user is executing in CICSPlex SM. 

The data sent from CICS to the Web browser is in HTML format, and is often 
large, resulting in large amounts of data flowing across the network, and slower 
response times. This is because all the data relevant to a request from the user is 
returned in a single response. If you repeat the request, all the information is 
resent from CICS to the Web browser. 

When you use the WUI, all communication between the Web browser is 
synchronous. The user has to wait for the HTTP response to the last input be 
returned from CICS before he can continue with his work. 
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CICS Explorer Plumbing 

In Figure 2-3 we see a high-level view of the CICS Explorer architecture. There is 
a lot more happening on the client side than in the WUI model. The client 
(Eclipse RCP) incorporates logic and data to handle the interface with the user, 
the state of the user session, and to hold information about the CICS 
configuration being used. This information extends to a detailed model of the 
CICSPlex being managed (based on the CICSPlex SM Resource Tables 
Reference model). 



Figure 2-3 CICS Explorer component architecture 


There is logic in CICS Explorer to cache data and manage the session, so CICS 
Explorer is not obliged to send an HTTP request to the WUI CICS region for each 
user interaction. Because CICS Explorer is managing the user interface, the data 
that flows from the WUI CICS region need not be HTML. In fact, CICS Explorer 
exchanges XML messages with the target WUI CICS region. 

Responsibility for holding information about CICS resources is shared between 
CICS Explorer and CICSPlex SM. In several cases, when the user makes a 
request for what might be a large amount of data, the WUI CICS region caches 
the requested data, and passes subsets of the cached data to the CICS Explorer 
only when they are requested. So, for example, as the user scrolls through a list 
of CICS regions, CICS Explorer sends requests for the next subset of data at the 
moment the user needs it. 
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3 


CICS Explorer SDK 


In this chapter we take an in depth look at the CICS Explorer SDK. The SDK 
provides a collection of Java objects that give a programmatic interface for 
creating, updating, and performing actions on CICS resources and definitions. 


© Copyright IBM Corp. 2010. All rights reserved. 
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3.1 CICS Explorer SDK Java library 


As discussed in Chapter 2, “CICS Explorer and the CICS Client Management 
Interface” on page 23, the CICS Explorer interacts with CICS using a RESTful 
interface. To facilitate a more productive Java programming experience, a 
collection of Java objects have been created that wrapper the generation of 
RESTful requests and the parsing of XML response data. Collectively, these Java 
objects are known as the CICS Explorer SDK. 

You can download the latest version of the CICS Explorer SDK by following 
these steps: 

1 . Go to the following Web site: 

http: //www-01 . i bm. com/software/htp/ci cs/expl orer/ 

2. Select Downloads -» CICS Explorer ->• CICS Explorer for CICS TS V4 
licensees Link to zip file. 

3. Input your IBM ID or register if you do not have one. 

4. Answer the questionnaire and agree to the license statement. 

5. Select CICS Explorer for CICS Transaction Server for z/OS V4.1 (SDK) 
and then click Download now. Your CICS Explorer SDK download then 
begins. 

6. After the download has finished follow the instructions detailed in “Creating 
your CICS Explorer plug-in development environment” on page 62 for 
installing into your Eclipse development environment. 

CICS Explorer SDK grows in parallel with the CICS Explorer. With the frequently 
planned code drops of the CICS Explorer, it is always worth investigating whether 
you have the latest version of the CICS Explorer SDK. 

The version discussed in this chapter is cicstsv41_explorer_sdk_vl002.zip. 

In the following sections we highlight the important objects in the CICS Explorer 
SDK, and explain how they are used. 


3.2 The CICSPlex System Manager object 

To get information about your CICSplex, or to perform actions on CICS systems, 
you need to have an instance of the CICSPlex System Manager (ICPSM) object. 
This is the main object you use to gain access to your CICS Explorer. 

Example 3-1 on page 47 shows how you obtain a reference to the ICPSM object. 
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Example 3- 1 Obtaining an instance of the ICPSM object 
ICPSM cpsm = UIPlugin.gefDe/auZf () .getCPSMQ ; 


With a reference to the cpsm object, you are able to retrieve basic information 
about the CICS regions to which you are connected. Example 3-2 shows how to 
obtain a selection of this information from the cpsm object. 


Example 3-2 Getting information from the ICPSM object 


System. out. println("Name: " + 
System. out. println("Host: " + 
System. out. println("Port: " + 
System. out. println("UserID: " 
System.ouf .println( "Connected: 


cpsm.getNameO); 
cpsm.getHost()) ; 
cpsm.getPortO) ; 

+ cpsm.getUserID()) ; 

: " + cpsm.isConnected()) ; 


The output generated from this code is shown in Example 3-2. 

Example 3-3 Output from Example 3-2 

Name: REDC // CMAS SYSIDNT 

Host: wtsc66 .itso.ibm. com / / Will hostname 

Port: 16001 // WUI port no. 

UserlD: CICSRS1 // Connected userid 

Connected: true// CICS Explorer connection to CICSplex 


The cpsm object also provides a mechanism for traversing the collection of 
CICSplexes and their managed CICS regions. Example 3-4 shows how to do 
this. 

Example 3-4 Getting CICSplex information from the ICPSM object 

II Iterate through the available CICSplexes and their regions 
for (ICICSplex cicsPlex : cpsm.getCICSplexesQ) 

{ 

System. out. println("CICSplex = " + cicsPlex. getNameQ) ; 

for (IManagedRegion region : 

cpsm.getManagedRegions (cicsPlex)) 


{ 

System. out. println("\tRegion = " + region.getName()) ; 
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The output generated from this code is shown in Example 3-5. 
Example 3-5 Our CICSplex and its CICS regions 


CICSplex: EPRED 
Region: EPREDW 
Region: EPRED1 
Region: EPRED2 
Region: EPRED3 
Region: EPRED4 
Region: EPRED5 
Region: EPRED6 
Region: EPRED7 
Region: EPRED8 
Region: EPRED9 


The cpsm object is also used for interacting with CICS resources and definitions. 
To do this, familiarize yourself with using contexts in the SDK. Contexts are 
discussed in 3.3, “Working with contexts” on page 48. 


3.3 Working with contexts 

In Example 3-4 on page 47 you retrieved the names of the CICSplexes known to 
this instance of CPSM. Next, we define what subset of those CICS resources we 
want to work with, lit one particular CICSplex? Or one particular CICS region? 

Contexts and scopes are mechanisms used in CICSPlex System Manager to 
provide scoping on the collection of CICS regions with which you want to work. In 
the simplest case you can set the context to the name of your CICSplex and the 
scope to an individual CICS region. In the CICS Explorer SDK utility classes 
have been created to represent contexts and scopes. There is also a class to 
enable advanced filtering. Example 3-6 shows an instance of context that is set 
to the name of a CICSplex. 

Example 3-6 CICSplex context 

Context pi exContext = new Context("EPRED") ; 


Example 3-7 on page 49 shows an instance of ScopedContext that is set to an 
individual region in the preceding CICSplex. In addition to passing the preceding 
object to the constructor of ScopedContext, you can also directly pass a string 
containing the CICSplex name, as shown in Example 3-7 on page 49. 
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Example 3-7 CICS region within CICSplex context 


ScopedContext scopedContext 

= new ScopedContext {plexContext , "EPRED4") ; 

// An alternative way of instantiating a ScopedContext object 
ScopedContext scopedContext 

= new ScopedContext ( " EPRED" , "EPRED4") ; 


For advanced filtering you can use the AbstractFilteredContext Java class. This 
class provides the ability to filter on any attribute of the resource on which you 
are filtering. Because AbstractFilteredContext is an abstract class it requires you 
to create a new Java class that extends it and implements the methods 
getAttri buteVal ue and getAttri buteNames. 

Example 3-8 shows an inner class that extends AbstractFilteredContext and 
returns all URIMaps in a CICS region that have the name MYURI. To scope it to 
a single CICS region, the scopedContext object is passed to the constructor of 
AbstractFilteredContext. 

Example 3-8 Filter on a URIMap resource in single CICS region within a CICSplex 

IFi 1 teredContext filteredScopedContext 

= new AbstractFil teredContext (scopedContext) 

{ 

public String getAttri buteVal ue(String argO) 

{ 

return “MYURI”; 

} 

public Set<String> getAttri buteNames () 

{ 

return Col lections. sir?gZefon(URIMapType. NAME. getCicsNameQ) ; 

} 

}; 


The call to URIMapType.NAME.getCICSName() returns the internal key for that 
attribute. This is used by CICSPlex System Manager to filter on that type. The 
class name “URIMapType” can be changed for any other CICS type. The value 
following it (which in this case is NAME) can be changed to any supported 
attribute on that type. The call to getCicsName() returns the string representation 
of that attribute. 
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You are not limited to passing a ScopedContext object to the constructor of 
AbstractFilteredContext. You can also pass in any other context object. 
Example 3-9 shows the use of AbstractFilterContext to filter on all URIMap 
definitions in a CICSplex. Note that a CICSplex wide context is passed to its 
constructor. 

Example 3-9 Filter on a URIMapDefinition resource in a CICSplex 

I Fi 1 teredContext fi l teredPlexContext 

= new AbstractFil teredContext (plexContext) 

{ 

public String getAttributeVal ue(String argO) 

{ 

return “MYURI”; 

} 

public Set<String> getAttributeNamesQ 

{ 

return Col 1 ecti ons .singleton (URIMapDef i ni ti onType .NAME. getCi csName () ) ; 

} 

}; 


The ability to filter on attributes doesn’t stop there. You can also filter on multiple 
attributes at the same time. Example 3-10 shows a filter that looks for all 
TSQueues in a CICSplex that have a name beginning with the letter “S” and a 
queue length of 128. 

Example 3- 1 0 Filtering on multiple attributes 

final HashMap<String, String> attributes 
= new HashMap<String, String>(); 

attributes. put (TSQueueType. NAME. getCi csName () , "S*") ; 

attri butes . put (TSQueueType . QUEUE_LENGTH . getCi csName () , " 128") ; 

I Fi 1 teredContext mul ti pi eFi 1 teredPl exContext 
= new AbstractFil teredContext (pi exContext) 

{ 

public String getAttributeVal ue(String argO) 

{ 

return attributes. get(argO) ; 

} 

public Set<String> getAttributeNamesQ 

{ 

return attributes. keySet () ; 

} 

}; 
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3.4 CICS objects 


When you retrieve resources using the CICS Explorer SDK, they are given as an 
instance of ICICSObject. If you want to work with a specific type, whether it is a 
resource or a definition, cast the ICICSObject to that type. Because all things are 
treated as ICICSObjects, there are generic utility methods supplied for retrieving, 
performing actions on, and updating them. 


3.4.1 Getting a CICS object 

To obtain a reference to a ICICSObject, provide a reference to the CICS type that 
you are after, and a context instance. The getModel () method of the cpsm object 
provides a mechanism which you can use to browse the results. 

Call model.activate() for the result set size to be calculated. Next, you have the 
ability to fetch results in chunks using the model .maybeFetch() method. The 
parameters to the method are the start and end index values respectively. Using 
this method enables you to minimize the results that are requested across the 
network at any one point. Finally, to get hold of each ICICSObject in, call 
model. get() and pass it an index value. Example 3-1 1 illustrates this. 

Example 3-11 Getting all the URIMapDefinitions in a CICSplex 
IResourcesModel model 

= cpsm. getModel (CICSTypes .URIMapDefinition, plexContext) ; 

model .activateQ ; // Initiate the model 

if (model .size() > 0) // Check there are objects to get 

{ 

ICICSObject [] cicsObjects = new ICICSObject [model .size()] ; 

model .maybeFetch(0, model .size()) ; // Fetch the results 

for (int i = 0; i < model .size() ; i++) 
cicsObjects[i] = model .get(i) ; 

} 


Note: For a full list of CICSTypes see Appendix A, “Reference list of CICS 
SDK elements” on page 303. 
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It is good practice only to retrieve the results that you need to show on the 
display, and to do this in a just-in-time basis. This is how the CICS Explorer 
works. You can use the model .size() method to get an idea of the result set size 
by calling model . size() , and fetch the results in incremental chunks using 
multiple calls to model .maybeFetch(). 

3.4.2 Performing actions on CICS objects 

When you are able to get hold of CICS objects as shown in Example 3-1 1 on 
page 51 , performing actions on them is easy. Using the cpsm object, pass the 
perform () method an array of CICSObjects and a reference to the action you 
want to perform. The perform () method declares that it can throw a 
CICSSystemManagerException if something goes wrong, so this needs to be 
dealt with by wrapping the call in a try/catch block. Example 3-12 shows the 
command for performing a disable action on CICS objects. 

Example 3- 12 Disabling multiple CICS objects 
try 
{ 

cpsm. perform (cicsObjects, SystemManagerActions.DisabZe) ; 

} 

catch (CICSSystemManagerException e) { e. printStackTrace O : } 


Note: For a full list of System ManagerActions see Appendix A, “Reference list 
of CICS SDK elements” on page 303. 


To perform a separate action such as a pipeline scan, you need to swap 
SystemManagerActions.Disable for SystemManagerActions.Scan. If you attempt 
to perform an action on a resource that does not support it (such as a pipeline 
scan on a program resource), a CICSSystemManagerException is thrown, as 
shown in Example 3-13. 

Example 3-13 Exception trace from performing an invalid command 

com. ibm. cics . core .model .CICSSystemManagerException: 
com. ibm. cics . sm. comm. sm. SMConnectionException : NOTFOUND, 
ACTION 
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3.4.3 Updating a CICS object 


To update a CICS object you first need to get a mutable version of it. This is done 
by casting your ICICSObject it to an ICoreObject and calling the getAdapter() 
method on the ICoreObject. The call to this method returns an instance of 
IMutableCoreObject that you cast to a mutable version of the object with which 
you are working. After updating various values on the object, feed the original 
reference to the IMutableCoreObject to the cpsm.update() method to commit the 
changes. 

Example 3-14 shows how to do this with an IMutableURIMapDefinition. The final 
call to the cpsm object needs to be wrapped in a try/catch block to deal with any 
CICSSystemManagerExceptions that might occur. 

Example 3-14 Updating a CICS object 

II Cast ICICSObject instance to an ICoreObject 
ICoreObject coreObject = (ICoreObject) cics0bjects[0] ; 

// Get an instance of IMutableCoreObject 
IMutableCoreObject mutabl eCoreObject = (IMutableCoreObject) 
coreObject. getAdapter (IMutableCoreObject. cl ass) ; 

// Convert it to an IMutableURIMapDefinition 
IMutabl eURIMapDef i ni ti on mutabl eURIMapDef i ni ti on 
= (IMutableURIMapDefinition) mutabl eCoreObject; 

// Update the description field 

mutabl eURIMapDef i niti on. setDescript ion ("New description") ; 

try 

{ 

// Commit the update 

IMutabl eCoreObject updatedMutabl eCoreObject 
= cpsm. update (mutabl eCoreObject) ; 

} 

catch (CICSSystemManagerException e) { e.printStackTraceQ ; } 


Note: For a full list of Mutable objects see Appendix A, “Reference list of CICS 
SDK elements” on page 303. 


The call to cpsm.update() returns you a reference to the updated object so that 
you can continue working with it if required. 
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3.5 Definitions 


When you want to create new resource instances using the CICS Explorer SDK, 
you need to create definitions for those resources. These definitions map to 
definitions in the CICS System Manager Business Application Services (BAS) 
repository or in the CICS CSD, depending on how the CICS Explorer is 
connected to your CICS systems. After creating a definition you are able to install 
or delete it. 


3.5.1 Creating a definition 

To create a new definition you need to create a IDefinitionBuilder for the resource 
type. The parameters you pass to the constructor of your definition builder are 
the minimum ones that are needed to create and install that resource. The 
remaining parameters inherit default values that can be updated by following the 
steps in Example 3-14 on page 53 on the returned IMutableCoreObject. 

Example 3-15 shows the code for creating a pipeline specific URIMap definition. 

Example 3-15 Creating a definition resource for a URIMap 

IDefinitionBui lder definitionBuilder 

= new Pi pel i neURIMapDef i ni ti onBui 1 der ("MYURIMap" , 

1L, 

"www.ibm.com" 

"/path", 

"MYPIPE") ; 


try 

{ 

IMutabl eCoreObject mutabl eCoreObject 

= cpsm. create (pi exContext, definitionBuilder); 

} 

catch (CICSSystemManagerException e) { e.printStackTraceQ ; } 


Note: For a full list of DefinitionBuilders see Appendix A, “Reference list of 
CICS SDK elements” on page 303. 
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Be aware: At the time of publishing there is an inconsistency in the error 
handling of the create command. If you attempt to create a definition that 
already exists then you get a com. ibm.cics.sm. comm. CreateException instead 
of a CICSSystemManagerException. The CreateException is a 
RuntimeException, so you are not forced to code a try/catch block for it. This 
means that you might forget to code for this case. If this happens, exception 
trace gets dumped to the stderr output stream if the error occurs. 

This inconsistency is resolved in a future version of the CICS Explorer SDK. 


3.5.2 Installing a definition 

Having created a definition the next stage is to install it. To do this, call the 
cpsm. install () method passing it the definition instance and a context in which 
to install it. Example 3-16 shows code for installing a definition. 

Example 3-16 Installing a definition 
try 
{ 

IDefinition instal ledDefinition 

= cpsm. instal 1 (uriMapDefinition, scopedContext) ; 

} 

catch (CICSSystemManagerException e) { e.printStackTrace() ; } 


If you try to get hold of the resource immediately after the install command, you 
might get no results back initially. This is because the install process causes an 
asynchronous task to install the resource from the definition. When the install has 
completed, you are able to retrieve a reference to it. 

Example 3-17 shows code that loops around until the resource has been 
installed. If you use this code you might want the loop to time out after a given 
number of iterations. Additionally, you must ensure that any thread waits happen 
on a background thread and not the main GUI thread, as discussed in 5.5, 
“Background process implementation” on page 138. 

Example 3- 1 7 Looping while you wait for a resource to be installed 
while (model .size() == 0) 

{ 

try { Thread. sleep ( 1000) ; } // Sleep for 1 second 
catch (InterruptedException e) {} 

model = cpsm. getModel (CICSTypes. URIMap, plexContext ) ; 
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model .acti vate() ; 


} 


3.5.3 Deleting a definition 

If you want to delete a definition, call cpsm.delete() and pass a reference to it. 
Example 3-18 shows how this is done. 

Example 3- 1 8 Deleting a definition 

try 

{ 

cpsm. delete(uriMapDefinition) ; 

} 

catch (CICSSystemManagerException e) { e.printStackTraceQ ; } 


3.6 Resources 

Previous sections have shown how to get, perform actions on, and update 
resources in CICS. The final stage of the life cycle is to be able to discard them. 

3.6.1 Discard a resource 

To discard a resource, you need to add them to an ICICSResource array, which 
is then passed to cpsm.discardResources(). Example 3-19 on page 56 shows a 
quick way of copying an array of ICICSObjects to an ICICSResource array, the 
contents of which are then discarded. 

Example 3- 1 9 Discarding resources 

ICICSResource[] cicsResources 

= new ICICSResource[cicsObjects. length] ; 

System . array copy ( ci csOb j ects , 0 , 

cicsResources, 0, 
cicsObj ects. length) ; 


try 


cpsm. di scardResource (cicsResources) ; 

} 

catch (CICSSystemManagerException e) 
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{ 

SMConnecti onExcepti on connecti onExcepti on 
= (SMConnecti onExcepti on) e.getCauseO ; 

System. out. printl n("ReasonName: " 

+ connectionException.getReasonNameQ) ; 

System . out . pri ntl n ( " ResponseName : " 

+ connectionException.getResponseNameO) ; 

System. out. pri ntl n("ResplName: " 

+ connectionException.getResplNameQ) ; 

System. out. printl n("Respl: " 

+ connectionException.getResplO) ; 

System. out. printl n("Resp2: " 

+ connectionException.getResp2()) ; 

} 


Additional error processing to visualize the difference between two separate error 
situations is included in Example 3-19. With this knowledge in mind, you are able 
to code for the separate situations. To get the response data, first obtain an 
instance of SMConnectionException. This is done by calling the getCauseQ 
method on the CICSSystemManagerException. 

If you attempt to discard a resource that does not exist, you see the values 
shown in Example 3-20. 

Example 3-20 Response values when attempting to delete a non-existent resource 

connectionException.getReasonName() : OK 
connectionException.getResponseName() : NODATA 
connectionException.getResplName() : nul 1 
connectionException.getResplO : 0 
connectionException.getResp2() : 0 


If you attempt to discard a resource before it has been disabled, you see the 
values shown in Example 3-21. 

Example 3-21 Response values when attempting to discard an enabled resource 

connectionException.getReasonName() : DATAERROR 
connectionException.getResponseName() : TABLEERROR 
connectionException.getResplNameQ : INVREQ 
connectionException.getResplO : 16 
connectionException.getResp2() : 4 
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Part 3 


Extending CICS 
Explorer 


In this part of this IBM Redbooks publication we discuss how to install and 
configure the development environment you use to develop your CICS Explorer 
plug-ins. We also provide more examples of plug-ins that can be coded to use 
IBM CICS Explorer in useful ways. 


© Copyright IBM Corp. 2010. All rights reserved. 
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4 


Writing a plug-in for CICS 
Explorer 


In this chapter we discuss how to install and configure the development 
environment you use to develop your CICS Explorer plug-ins. After the 
development environment is set up, we work through a “Hello World” plug-in 
example to get us started. After we have got our “Hello World” example, we use it 
as a vehicle to discover the various ways in which we can interact with the user 
and with CICS Explorer. 


© Copyright IBM Corp. 2010. All rights reserved. 
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4.1 Creating your CICS Explorer plug-in development 
environment 


Before you can develop your own CICS Explorer plug-ins, you need to install and 
configure the development environment. There are three components that you 
need to consider when setting this up: 

► Java Virtual Machine 

► Eclipse Classic SDK 

► CICS Explorer SDK 

Important: It is critical that you have the right software levels of all three of 
these components, and that you are using the correct JVM when installing the 
other components. Check the required levels for the version of the CICS 
Explorer SDK that you are using. 


We used the following software levels for this Redbooks publication: 

► Java Version 1 .6.0 (build pwi3260sr5-20090529_04(SR5)) 

► IBM CICS Explorer Version 1 .0.0.2 [build id: 200909240951] 

► Eclipse SDK Version 3.5.1 (Build id: M2009091 7-0800) 

► IBM CICS Explorer Version 1 .0.0.2 [build id: 200909240951] 

4.1 .1 Setting up the Java environment 

Ensure that you have the correct JVM installed and configured before you install 
the other components on your workstation. If you are using the latest version of 
CICS Explorer, you need Java Version 1 .6. To determine the default version of 
Java running on your Windows® machine, open an MS-DOS window, and enter 
the command java -version. This command tells you whether there is a version 
of Java currently installed, and the version number. If it is not 1.6.0, download 
and install the later JVM. 

If you do not have the correct version of Java, you can download it from the 
following Web page: 

http://www.ibm.com/developerworks/java/jdk/ 

In this example, we downloaded the ibm-java-sdk-60-win-i386.zip file. After 
you download the necessary .zi p file, extract it. We extracted the file to the 
C:\software\ibm-java-sdk-60-win-i386 directory. 
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To make sure that the Java installation is successful, in an MS-DOS window, go 
to the c:\ibm-java-sdk-60-win-i386\sdk\bin directory and enter the java 
-version command. You see the messages shown in Figure 4-1. 



Now that you have the correct version of Java installed in your machine, you can 
install the Eclipse SDK. 


4.1 .2 Installing the Eclipse SDK onto your workstation 

After you have verified which version of the Eclipse SDK you are working with (in 
our case it is Eclipse SDK Version 3.5.1), you can download it from the following 
Web page: 

http://www.ecl ipse.org/downloads 

We downloaded file eel ipse-SDK-3. 5. l-win32.zip, and extracted the contents 
into directory eclipse-SDK-3. 5.1 -Win32. 

Before you run Eclipse for the first time, verify that it runs with the Version 1 .6 
JVM you installed earlier. We did this by creating an executable called 
startEcl i pse . bat in the C : \sof tware directory. This executable passes the 
address of the correct JVM when starting Eclipse. The source code for this .bat 
file is shown in Example 4-1 . 

Example 4- 1 Source code to launch Eclipse pointing to correct JVM 

C : \software\ecl i pse-SDK-3 . 5 . 1-wi n32\ecl i pse\ecl i pse -vm 
C:\software\ibm-java-sdk-60-win-i386\sdk\bin 
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Using Windows CICS Explorer, open C:\software\ and double-click 
startEcl ipse.bat to execute it. Your Eclipse workspace folder contains all the 
Eclipse artifacts that you create in the course of your plug-in development. For 
now, use the default workspace name and click OK. You see the Eclipse 
welcome panel displayed in Figure 4-2. 



Figure 4-2 Eclipse Welcome panel 
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After you have Eclipse up and running, it is worth updating it to point to the Java 
1 .6 environment as its default runtime. Do this by clicking Window 
Preferences Java -» Installed JREs. The panel shown in Figure 4-3 is 
displayed. 



Figure 4-3 Set default JRE for Eclipse (EclipseDefaultJVM.gif) 

Click Add ->• Standard JVM ->• Next. Click Directory and select the home 
directory of your Java 1 .6 JRE (in our case this directory is 
C:\software\ibm-java-sdk-60-win-i386\sdk), and click Finish. Select this JRE 
as the default for Eclipse to use and click OK. 

You have now successfully created your Eclipse SDK environment. You are 
ready to develop your first Eclipse plug-in. 


Note: So far, we have not installed any CICS code into Eclipse. We are just 
working with the environment provided by the Eclipse platform. 
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4.2 An Eclipse RCP “Hello World” plug-in 


When you create your Eclipse SDK environment, it includes a set of templates 
and wizards to generate code skeletons that you can modify to add your own 
code. The Eclipse plug-in environment is Java-based, so you need to do Java 
coding to handle communications with the user and invoke business functionality 
behind (which might be Java). Working with the Eclipse “Hello World” samples is 
a good way to learn about coding for the Eclipse user interface. 


4.2.1 Creating your plug-in project 

Whenever you do something in Eclipse, you do it in the context of a project. You 
can think of a project as a folder in which Eclipse stores all the information and 
resources associated with this activity. There are many projects, depending on 
the task which you are executing. Because you want to create a new Eclipse 
plug-in, you are going to create a plug-in project. 

You begin by creating a new Workspace. Start your Eclipse workbench, and 
create a new workspace. We called ours HelloWorldWorkspace. Because it is a 
new workspace, you are presented with the Eclipse Welcome panel. 

Close the Welcome panel. You are presented with the Java Developers 
perspective. Click Window Open Perspective Other and select the 
Plug-in Developer perspective. You can see the layout is similar to the default. 
The difference is that the tab hidden behind the Package CICS Explorer view, in 
the navigation pane tab group on the left side of the panel, is a view called 
Plug-in. If you click the tab, you see the panel shown in Figure 4-4 on page 67. 
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ta Package Explorer , Plug-ins £3 1=1 B 

Filter matched 229 of 403 plug-ins. ^ j 

fit ^ | B ^ 

org.edipse. ant. core (3.2. 100 .v20090e(* | 

Xj> org. eclipse. ant.ui (3.4. l.v 2009090 l_r 
v)> org.edipse. compare (3.5.0.120090514 
Xj> org.edipse. compare. core (3.5.0.12009 
Xi> org.edipse. compare. Win32 (1.0.0.I20C 
Xf> org.edipse. core. boot (3. 1. 100.V2008C 
org.edipse.core.commands (3.5.0.I20C 
X> org.edipse.core.contenttype (3.4. l.R: 

Xj> org.edipse.core.databinding (1.2.0. Mi = 

Xt> org.edipse.core.databinding. beans (1. 
v> org . edipse . core . da tabinding . observab 
\> org . edipse . core, da tabinding . property 
org. edipse. core. expressions (3.4.100. 

X> org. edipse. core.filebuffers (3.5.0.v20i 
X> org.edipse.core.filesystem (1.2.0.v20( 

Xp* org . edipse . core . filesystem . win 32. x86 
X)> org. edipse. core.jobs (3.4.100.v20090 
Figure 4-4 Plug-in view 

These are all the plug-ins that make up the Eclipse SDK. They are available for 
re-use by your new plug-in. After you have coded you own plug-ins, they can be 
available for re-use in the same way. Click the Package CICS Explorer tab to 
return to the Package CICS Explorer view. It is currently empty. 
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To create your new plug-in package, click File -> New ->• Project to start the 
New Project wizard. Select Plug-in Project (not Plug-in-Development), and click 
Next. You are presented with the panel shown in Figure 4-5. 



Figure 4-5 New Plug-in project wizard 

Give the new project a name. We called ours “HelloWorldOne.” Leave the other 
values set to their default values. Click Next. 

The next panel in the wizard asks you to give more details about the plug-in 
content. You can keep all the default values. We need an activator class (more 
about this later). We want to generate a plug-in that interfaces with the user. You 
are not creating an entire new Eclipse RCP application. Click Next. 
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Fortunately, Eclipse comes with a rich set of examples that can be used to 
familiarize ourselves with programming in this environment. At this point in the 
New Plug-in Project wizard, Eclipse gives a list of possible examples, or 
templates, on which you can base your new plug-in. This is shown in Figure 4-6. 



Figure 4-6 List of plug-in templates provided by Eclipse 
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Try selecting each of the templates in turn. A description of the template appears 
in the pane on the right. When you have finished browsing the list, select the 
Hello, World template. 


The wizard proceeds with the creation of your plug-in, and presents you with a 
panel summarizing the plug-in that you are creating (see Figure 4-7). Click 
Finish to create the plug-in. 



Figure 4-7 First Hello World plug-in details 
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After you have clicked Finish in the New Plug-in Project wizard, the plug-in is 
created. In the Package CICS Explorer view on the left side, you can see the 
various objects that have been created. See Figure 4-8. 



Figure 4-8 Plug-in Overview view 


Run the plug-in so that you can see exactly what it does. One of the great things 
about Eclipse is that after you have written your plug-in, it is easy to test it. 

To run the plug-in, in the Package CICS Explorer view, right-click the 
HelloWorldOne project, and select Run as -» Eclipse Application. You see that 
a completely new instance of Eclipse is started, with a new workspace. Close the 
Welcome window, and look closely at your new workspace. Can you see what 
has changed? 

Hint: Look closely at the workspace menu bar and toolbar. 
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Figure 4-9 shows the workspace generated when you test the HelloWorldOne 
sample. This Hello world example adds a new item “Sample Menu” to the 
workspace menu bar, and a new icon to the workspace toolbar (because no 
specific icon is referenced in the sample, it uses the default Eclipse icon). 
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Figure 4-9 HelloWorldOne test 


If you now left-click the icon, or left-click Sample Menu and select Sample 
Action, a window appears in the workspace with our “Hello World” message 
(see Figure 4-10). 



Figure 4-10 Hello World One Sample Action 


If you create and run projects using the other Hello World templates provided by 
Eclipse, you see other examples of user interaction. 
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4.2.2 What is in our HelloWorld plug-in project? 


The manifest editor displays the Overview view of the plug-in in the upper central 
panel. This gives a user-friendly version of the contents of the mani fest .mf and 
pi ugin.xml files. Double-click the Overview tab to get a full-panel display. Click 
the MANIFEST.MF tab following this view (Example 4-2), and you see the raw file 
(which is less verbose than the overview). 

Example 4-2 HelloWorldOne manifest. mf 

Manifest-Version: 1.0 

Bundle-ManifestVersion: 2 
Bundle-Name: HelloWorldOne 

Bundle-Symbol icName: HelloWorldOne; singleton :=true 
Bundle-Version: l.O.O.qual ifier 
Bundle-Activator: hel loworldone. Activator 
Bundle-Vendor: Steve 
Require-Bundle: org. eel ipse. ui , 
org. eel ipse. core. runtime 

Bundle-RequiredExecutionEnvironment : JavaSE-1.6 
Bundle-ActivationPol icy: lazy 


The manifest.mf contains information about the origin, version, and run-time 
environment of the plug-in. 

The details about the dependencies of our plug-in, and its relationship to other 
plug-ins is provided in the plug- in. xml file. Click the plugin.xml tab, and you see 
the HelloWorldOneplug-in.xml file (Example 4-3). 

Example 4-3 HelloWorldOneplug-in.xml 
<?xml version="1.0" encoding="UTF-8"?> 

<?eclipse version="3.4"?> 

<plugin> 

extension point="org. eel ipse. ui .actionSets"> 

<actionSet 

label=" Sample Action Set" 
visible="true" 

id="Hel loWorldOne.actionSet"> 

<menu 1 abel ="Sampl e &amp;Menu" id="sampl eMenu"> 
separator name="sampleGroup"> 

</separator> 

</menu> 

<action 1 abel ="&amp; Sample Action" 
icon=" i cons /sample. gif" 
cl ass= " hel loworldone. actions. SampleAct ion" 
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tool tip="Hello, Eel ipse world" 
menubarPath="sampleMenu/sampleGroup" 
tool barPath="sampleGroup" 
id="hel loworl done. act ions. SampleActi on "> 
</action> 

</actionSet> 

</extension> 

</pl ugin> 


The extension tag tells Eclipse the Java class which this plug-in is extending (in 
this case, the org.eclipse.ui.actionSets class). This is the class that manages the 
Eclipse menu bar and toolbar. Our HelloWorldOne class is going to interact with 
these two parts of the Eclipse workspace (you can also see this information by 
clicking the Extensions tab). Within the extension tag are more details about the 
additions to the menu bar and toolbar (the icon to appear on the toolbar, the 
name of the new tab in the menu bar, and associated information). Most 
important of all, the class parameter tells Eclipse which Java class to invoke to 
perform our new action (helloworldone.actions.SampleAction). 

Click the Dependencies tab underneath this view and you see that your new 
plug-in relies on two packages that are provided by the Eclipse base platform: 

► classes org.eclipse.ui 

► org.eclipse.core.runtime 

These two packages correspond to those specified on the Require-Bundle 
parameter in the mani fest .mf file. 

If you click the Extension Points tab, you see that there are none. This is because 
our plug-in does not expose any interfaces that are to be used by other plug-ins. 

Double-click the Extension Points tab to return to the Plug-in perspective default 
view showing the Package CICS Explorer view. 

HelloWorldOne Java implementation 

You can see that as well as creating the mani fest. mf and plugin, xml code, the 
wizard has generated other objects, including the Java packages that implement 
the plug-in. In fact, two Java packages have been created; the helloworldone 
package contains the Activator.java class, and the helloworldone.actions 
package contains the SampleAction.java class, as shown in Figure 4-1 1 on 
page 75. 
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The Activator.java object has been created because during the creation of our 
Plug-in project, we left the “Generate an activator” check box selected. The 
Activator.java object is used to allow the programmer to execute any actions that 
might need to be performed during the life cycle of our SampleAction object (for 
example, there might be a need to execute code at the moment this object is 
started, and at the moment it is stopped). It is also invoked to allow a caller to 
inquire on the icon associated with our SampleAction object. The generated 
object is effectively a no-op for the methods, which you modify to add the start 
and stop functionality you want to implement. 

Because our HelloWorldOne sample does not require any work to be done when 
it is started and stopped, we could have chosen to clear the “Generate an 
Activator” check box. In this case, the Activator.java class would not have been 
generated for our plug-in. It still executes without error. 

Click the SampleAction.java file, and you are presented with the Java source 
code for our HelloWorldone plug-in. Double-click the SampleAction.java tag to 
get a full panel view of the code. 
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The generated code can be broken down into the parts shown in Example 4-4. 
Example 4-4 HelloWorldOne package and import statements 


package hell oworl done. actions; 

import org. eel ipse. j face. acti on. IAct ion; 

import org. eel ipse. jface. viewers. ISelection; 

import org. eel ipse. ui . IWorkbenchWi ndow; 

import org. eel ipse. ui . IWorkbenchWi ndowActionDelegate; 

import org. eel ipse. jface. dialogs. MessageDialog; 


Because you are using a function provided by Eclipse, you need to import the 
necessary packages. These packages are all related to interacting with the 
Eclipse user interface. When you start using the function provided by CICS 
Explorer, you need to add import statements for packages supplied by CICS 
Explorer, rather than by Eclipse. 

lAction, ISelection, IworkbencWindow, and IworkbenchWindowActionDelegate 
are interface classes. This means they define the interfaces used to 
communicate between the Eclipse user interface component, and your 
helloworldone component. As the implementer of helloworldone, it is your 
responsibility to provide the code that implements the business function to be 
executed when your action is invoked, and return the expected output. 

MessageDialog is the class used to interact with the user by sending “hello 
World” to the panel. Our code invokes this plug-in, which is provided by Eclipse. 

In Example 4-5 we see the class definition and constructor for our class. 
SampleAction implements the IworkbenchWindowActionDelegate interface. This 
is how the Eclipse plug-in architecture works. To create a new Eclipse entity such 
as a perspective, a view, or (as in this case) an action, Eclipse creates a proxy 
object and delegates responsibility for executing the requested method to the 
associated object (as defined in the plugin. xml file). Make sure that all the 
necessary code is in place. 

Example 4-5 Class definition and constructor for SampleAction 

public class SampleAction implements IworkbenchWindowActionDelegate { 
private IWorkbenchWi ndow window; 

/** 

* The constructor. 

*/ 

public SampleAction() { 

} 
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Methods associated with our HelloWorldOne class 

The following methods (as defined in the lActionSet interface class) have been 
generated for our SampleAction class: 

► init 

This method is invoked when your ActionSet becomes active. It gains access 
to the Workspace window, and saves it for later use. See Example 4-6 for 
example. 

Example 4-6 Init method of Hello WorldOne 

* We cache window object to be able to 

* provide parent shell for the message dialog. 

* @see IWorkbenchWindowActionDelegatelinit 
*/ 

public void init(IWorkbenchWindow window) { 
this. window = window; 

} 


The user has clicked on the icon or chosen this action from the menu bar. The 
window object was initialized by the init method. We invoke its getShel 1 
method to give ourselves the ability to write to the panel. 

We use the MessageDialog class supplied by Eclipse to open an information 
window and put out our Hello World text message. See Example 4-7. 

Example 4-7 Run method of HelloWorldOne 
/** 

* The action has been activated. The argument of the 

* method represents the 'real' action sitting 

* in the workbench UI. 

* @see IWorkbenchWindowActionDelegatelrun 
*/ 

public void run(IAction action) { 

MessageDi al oq .openln formation ( 
window. getShel 1 (), 

"Hel loWorldOne", 

"Hello, Eclipse world"); 

► selectionChanged 

The selectionChanged method is a no-op in this example. The 
selectionChanged method is invoked when the cursor is clicked on our action. 
Prior to running the init method. u rpr. having selected this action, the user 
changes his mind, allowing you to undo anything done in the Run method. 
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► dispose 

The dispose method is a no-op in this example. The dispose method is 
invoked to clean up when the object is being destroyed. 

Java implementation summary 

We have seen that Eclipse can generate useful Java code templates. Now we 
see how we can take those templates and fill them out with more functionality, 
and then we can start building messages with CICS content and putting them out 
to the panel. 


4.3 Creating your first CICS Explorer plug-in 

Now that we have seen how the wizards provided by Eclipse can be used to 
generate template code, we follow the process detailed in 4.2, “An Eclipse RCP 
“Hello World” plug-in” on page 66, but we add CICS Explorer code to give our 
HelloWorld a more CICS feel. 


4.3.1 Creating your CICS Explorer plug-in project 

Start the Eclipse SDK that has the CICS Explorer installed into it. Click 
Window ->• Open Perspective ->• Other and select the Plug-in Developer 
perspective. This is the perspective with which you are working. 

If this is not already shown, click the Plug-in view in the left pane. Scroll through 
the list. You see plug-ins that are provided in the CICS Explorer SDK, as shown 
in Figure 4-12 on page 79. 
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Figure 4-12 CICS Explorer content in Plug-in view 


Click the Package Explorer tab to return to the Package Explorer view. It is 
currently empty. 
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To create your new plug-in package, click File -> New ->• Project to start the 
New Plug-in Project wizard. Select Plug-in Project a (not Plug-in-Development), 
and click Next. You are presented with the window shown in Figure 4-13. 



Figure 4-13 New Plug-in Project wizard 

You need to give the new project a name. We called ours “CICS Explorer 
HelloWorld.” The other values can remain with their default values. Click Next. 

The next window in the wizard asks you to give more details about the plug-in 
content. As we have already seen, you do not always need an Activator class. 
Clear the box so that no Activator class is generated for your new plug-in. Allow 
the other settings to default. You want to generate a plug-in that interfaces with 
the user, and you do not want to create a new Eclipse RCP application. Click 
Next. 

On the next panel, where you are presented with a list of plug-in samples and 
templates, select the same Hello, World template used in 4.2, “An Eclipse RCP 
“Hello World” plug-in” on page 66. This time, we are going add CICS Explorer 
functionality to the generated code. 
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The wizard proceeds with the creation of the HelloWorld plug-in, and presents 
you with a panel summarizing the plug-in that you are creating (see Figure 4-14). 
Change the Action Class Name to CICS Expl orer Hel 1 oWorl d and click Finish to 
create the plug-in (we are going to add code to change the Message Box Text). 



Figure 4-14 CICS Explorer Hello World plug-in details 


After you have clicked Finish in the New Plug-in Project wizard, the plug-in is 
created. In the Package Explorer view on the left side, you can see the various 
objects that have been created. See Figure 4-15. 



Figure 4-15 CICS Explorer HelloWorld Plug-in Overview view 
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At this stage, the only difference between our CICS Explorer HelloWorld plug-in 
and the one we created in4.2, “An Eclipse RCP “Hello World” plug-in” on page 66 
is the name of the generated package file and Java class class file. 


4.3.2 Adding CICS Explorer to plug-in dependencies 

You are going to use Java code provided by the CICS Explorer SDK, so you need 
to tell Eclipse that your ExplorerHelloWorld project has dependencies on plug-ins 
supplied by the CICS Explorer SDK. Do this by clicking the Dependencies tab in 
the central pane at the bottom of the Overview Editor . 

Click Add in the Imported Packages pane on the right side of the Dependencies 
view, and add the following packages: 

► com.ibm.cics.core.comm 

► com. ibm.cics. core. model 

► com.ibm.cics.core.ui 

► com.ibm.cics.model 

4.3.3 Adding CICS Explorer code to the Eclipse Template code 

Now you are going to modify the code in the generated Java code to use 
functionality provided by the CICS Explorer SDK. Replace the supplied run 
method of your ExplorerHelloWorld class with the one shown in Example 4-8. 

Example 4-8 ExplorerHelloWorld run method 
public void run(IAction action) { 

ICPSM cpsm = (ICPSM) 

UIP1 ugin.getDefaul t() .getResourceManager 
(UIP1 ugi n.SYSTEM_MANAGER_CONNECTION_ID) ; 

ICICSpl ex[] plexes = cpsm.getCICSplexes() ; . 

String pi exString = 

for (ICICSplex plex : plexes) plexString += pi ex.getName() 


// DELME 

IManagedRegion[] regions = 
cpsm.getManagedRegi ons (pi exes [0] ) ; 
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String regionstring = 

for (IManagedRegion region : regions) regionstring += 
region. getName() + " 


MessageDialog.openInformation( 
window. getShel 1 () , 

"Hel 1 o_Worl d" , 

"Hello" + 

"\nYou are logged in to CPSM as " + cpsm.getUserID() 

"\nYour server name is " + cpsm.getName() + 

"\nYour CICSplex name is " + pi exString + 

"\nYour regions are is " + regionstring); 


After you have copied the code in Example 4-8 on page 82 into the editor in 
Eclipse, you see that there are now a number of errors signalled by Eclipse, as 
shown in Figure 4-16. 



Figure 4-16 ExplorerHello World dependencies 
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Your ExplorerHelloWorld plug-in now has dependencies on other plug-ins. You 
must tell Eclipse which plug-ins or packages are to be used to resolve those 
dependencies. 


Tip: Follow this suggestion to avoid spending time trying to map CICS 
Explorer objects to their appropriate packages. 


You are going to be working with CICS Explorer objects that are scattered across 
a large number of CICS Explorer-supplied plug-ins. Eclipse provides the 
Navigate facility to find the Java package containing an object that you want to 
use. However, you have to tell Eclipse that you want the CICS Explorer plug-ins 
to be included in its searches. Click the Plug-in tab to show the Plug-in view on 
the left pane, then click the last icon on the toolbar of the Plug-in view in the left 
pane (As you hold the cursor over this icon you see the text “Add All Plug-ins to 
Java Search.” See Figure 4-17). Eclipse now includes the CICS Explorer plug-ins 
in its searches for Java artifacts.) 
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Figure 4-17 Add All Plug-ins to Java Search 


You only have to add all plug-ins to a Java search in this manner when you have 
added more plug-ins. 

Return to the editor view containing your ExplorerHelloWorld.java file, and 
identify the first Java statement that is in error. It appears to be the ICPSM object 
that is causing the problem. 

Click the Navigate tab on the workspace action bar, and select Open Type. The 
panel shown Figure 4-18 on page 85 is displayed, showing that the ICPSM 
object is to be found in package com.ibm.core.model. 
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Figure 4-18 ICPSM object is to be found in package com. ibm. core, model. 

You need to declare package com.ibm.core.model as an external dependency. 
Do this by returning to the Manifest Editor view, which was opened when we 
created our ExplorerHelloWorld project. Double-click the Dependencies tab at 
the bottom of the central pane, and then double-click the tab to get the panel view 
shown in Figure 4-19. 



Figure 4-19 Declare package com.ibm.core as dependency 
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Click Add in the Required Plug-ins pane. The Plug-in selection window displays. 
Enter the name of the package you found with navigator. (The window prompts 
you with a list of suitable matches as you type in the characters) Click OK to add 
this plug-in to the list of dependencies. See Figure 4-20. 



Figure 4-20 Plug-in added 


You need to add import statements for the CICS Explorer packages you are 
using to the ExplorerHelloWorld.java file. When you have the correct 
dependencies in place, you can resolve missing imports by placing the cursor 
over unresolved objects. Eclipse offers to find the missing import for you. Put the 
cursor on the Import option in the list, and Eclipse adds the required import 
statement. See Figure 4-21 on page 87. 


Extend the CICS Explorer: A Better Way to Manage Your CICS 



©. ExplorerHelloWorld 

1 ExplorerHelloWorld .java £3 Node$PlugIn.dass 

= a 


- public 

void run<IAction action) { 


0- 

* 

(UI Plugin . S YS TEM_MANAGER_ CCNNEC TI CN_ I D ) ; 

etResour 




ICICSplex [ ] plexes * cpsm.getCICSplexes () ; 





String plexString 





for (ICICSplex plex : plexes) plexString += 

plex. get 


a 


regions = cpsm.getManagedRe 

gions (pi 




ij IManagedRegion cannot be resolved to a type 


j 

a 

— 

J - Imoort ’IManaoedReaion' ( com. ibm.acs. model) 0 





Q Create enum 'IManagedRegion' 

° type parameter -IMena q edRe q ,on' ,o 'ExplorerHelloWorld 










I>1 



Figure 4-21 Using Eclipse to resolve missing objects 


If you put the cursor over an object, and Eclipse cannot find it, then you need to 
add another dependency as described previously. 

After you have successfully resolved all the missing objects, press Ctrl+S to save 
the changes to the workspace. 

When you are ready to run the plug-in, in the Package CICS Explorer view, 
right-click the ExplorerHelloWorld project, and select Run as -» Eclipse. 
Application. You see that a completely new instance of Eclipse is started, with a 
new workspace. 
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Figure 4-22 shows the workspace generated when you test the 
ExplorerHelloWorld sample. You can see that it looks much the same as our 
original HelloWorldOne example. The “Sample Menu” item is in the workspace 
menu bar, and the new icon is in the workspace toolbar. 
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Figure 4-22 ExplorerHelloWorld Test 


Because your ExplorerHelloWorld plug-in accesses CICSPlex SM, you need to 
make sure we are connected to CICSPlex SM before we try to run it. Click 
Window Open Perspective Other and select the CICS SM perspective. 
Configure the connection to your CICS WUI Server using the CMCI interface. 
When you have successfully connected to your CICS WUI Server you are ready 
to try out your new plug-in. 

If you left-click the icon, or left-click Sample Menu, and select Sample Action, a 
window appears in the workspace (Figure 4-23 on page 89 ). 
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Figure 4-23 ExplorerHelloWorld Sample Action 


Our plug-in has requested CICSPlex SM configuration information from the CICS 
WUI region. The server name is the SYSID of the CMAS to which the CICS WUI 
Server is connected, the rest is self-explanatory. 

You can now close down the Eclipse in which your ExplorerHelloWorld is 
running. 

You can make the plug-in look a lot more CICS-centric by changing some of the 
information in the plugin, xml file. Return to the Package Explorer view of your 
development Eclipse, and double-click the plugin, xml file, to open the 
plugin. xml editor. Make the changes highlighted in red in Example 4-9, presse 
Ctrl+S to save the changes, and re-run the test. 


Note: You need to copy an appropriate icon into the icons directory of your 
ExplorerHelloWorld project. 


Example 4-9 Plug-in XML changes in red 

<pl ugin> 
extension 

poi nt="org.ecl ipse.ui . act i onSets "> 
<actionSet 

label ="CICS Explorer Hello World" 

visible="true" 

id="ExplorerHel loWorld. act i onSet "> 
<menu 

1 abel = CICS Explorer &amp;Menu" 
id="sampleMenu"> 
separator 

name="sampleGroup"> 
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</separator> 

</menu> 

<action 

label ="&amp;CICS Explorer Hello World 
icon="ico CICSExplorerIcon.GIF 

cl ass="expl orerhel 1 oworl d . acti ons . Expl orerHel 1 oWorl d" 
tooltip="Hel lo, Eel ipse world" 
menubarPath="sampleMenu/sampleGroup" 
tool barPath="sampleGroup" 

i d= " expl orerhel 1 oworl d . actions . Expl orerHel 1 oWorl d"> 
</action> 

</actionSet> 

</extension> 

</pl ugin> 


When you re-run the test, you get a more CICS-centric action tab and icon 
(Figure 4-24), although the function has not changed. 



Figure 4-24 Customized ExplorerHelloWorld 


4.3.4 CICS Explorer plug-in design consideration 

When your ExplorerHelloWorld plug-in requested information from CICSPlex SM 
itself, there was a delay between requesting the action, and CICSPlex SM Hello 
World message appearing on the window. During this period you were not able to 
do anything in your Eclipse environment. 

When you want to use the CICS Explorer classes to connect to the CICS WUI 
region, create a new thread specifically for executing the call to the WUI region. 
Then your workspace GUI thread can execute while you wait for the call to 
CICSPlex SM to complete. When the operation completes, the communication 
thread passes the results back to the workspace thread for display. 
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You are now going to modify ExplorerHelloWorld to work in this way. To achieve 
this you must insert inline class methods into the existing code, and modify the 
existing code to use them. 

Move the variables accessed by the CPSM to be global across all methods of the 
class, as shown in Example 4-10. 

Example 4-10 Move the variables accessed by the CPSM 

private String pi exString = 
private String regionstring = 


Change the run() method of the ExplorerHelloWorld object as shown in 
Figure 4-25. 


public void run(IAction action) { 

final Job job = new Job( n MyJob”) 

{ 

protected IStatus run (final IProgressMonitor monitor) Q 


//This is the command that causes all the 
// above to execute ! ! ! ! 
j ob . schedule ( ) ; 


Figure 4-25 Change the run() method of our ExplorerHelloWorld object 

The statement final Job job = new Job(“MYJob”) tells Eclipse that you are 
going to be running a piece of work job under a separate execution thread. This 
piece of work is executed when you invoke the schedul e method of your job 
object job. schedule. You can see that there is more code between these two 
statements. The code between the two contains the inline run() method that 
contains the code to be executed on the separate thread. If you click the cross on 
the right side of the display, Eclipse expands the inline class and you see the 
code shown in Example 4-11 on page 91. We have highlighted the interesting 
parts of the text. 

Example 4-11 Progress bar run method 

protected IStatus run (final IProgressMonitor monitor) 

{ 

// Start the progress bar running 

monitor. beginTask("MyJob" , IProgressMonitor .UNKNOWN ) ; 

// Do the CPSM stuff here 
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// This is the big CPSM call that gives us the CPSM 

// context we can use to invoke CPSM !!!! 

final ICPSM cpsm = UIP1 agin. getDefault () .getCPSM() ; 

// Get the names of the CICSPlexes 

// that this WUI knows about 

ICICSpl ex [] plexes = cpsm.getCICSplexes() ; 


// Write out the CICSPlexes returned 

for ( ICICSpl ex plex : plexes) plexString += pi ex.getName() + 


// Ask CPSM for the CICS regions it knows about 
IManagedRegion[] regions = 
cpsm. getManagedRegi ons (pi exes [0] ) ; 

// Write out the CICS region names returned 

for (IManagedRegion region : regions) regionstring 

region. getName() + " 

//Tell the GUI thread that we want it to do some 
//stuff that we have implemented by an i nl i ne run() 

//method. 

Display. getDefault{) .asyncExec(new Runnable() 


POverride 

public void run() { 

// T0D0 Auto-generated method stub 
// Moved the CPSM screen formatting to 
// be executed when we have grabbed back 
// the GUI thread. 

MessageDi al og .openln formation ( 
window. getShel 1 () , 


"Hel 1 o_Worl d" , 
"Hello" + 


cpsm.getUserID() + 


}); 


} 


"\nYou are logged in to CPSM as " + 

"\nYour server name is " + cpsm.getName() 
"\nYour CICSplex name is " + plexString + 
"\nYour regions are " + regionstring); 
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monitor. done() ; 


return Status .OK_STATUS; 

} 

}; 
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5 


Extending CICS Explorer 
plug-ins 


In this chapter we provide meaningful examples of plug-ins that can be coded to 
use IBM CICS Explorer in ways specific to a business or enterprise, or which 
allow the CICS data managed by CICS Explorer to be accessed in new and 
interesting ways (which are not possible with the standard CICS Explorer 
implementation). We look at the separate user interfaces which Eclipse provides 
to do this. 

We take a step by step approach: 

► Extending new CICS Explorer views 

► Using a pop-up menu to access URIMap information 

► Extending a toolbar to access URIMap information 

► Extending a toolbar to add a filter based on user input 

► Background process implementation 

► Summary of extending functions 

► Package all extending functions into a plug-in 


© Copyright IBM Corp. 2010. All rights reserved. 
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5.1 Extending new CICS Explorer views 


In this section we look at how we can extend new CICS Exploerer views. 

5.1.1 Extending the URIMap information provided by CICS Explorer 

We provided details on developing a sampleView”in Chapter 4, “Writing a plug-in 
for CICS Explorer” on page 61 . In this section, we describe how to modify a 
sampleView to be a more practical one. As a practical example, we apply 
URIMap resource information to the sampleView. A URIMap is CICS resource 
definition that maps the URI of an incoming HTTP or Web service request to how 
CICS processes the request. URIMap attributes have a hierarchical structure. 

We use URIMap related information as an example of how to create a new view 
showing CICS resources. Our sample code in this chapter implements separate 
processes depending on the URIMap attribute: SERVER, CLIENT, PIPELINE, or 
ATOM as USAGE parameter. For example, if USAGE=SERVER, you can get and 
display PROGRAM information. 

5.1.2 Specification of new view 

The new CICS Explorer view provides detailed information about a URIMAP, 
which can be selected by clicking on it in the URIMap view. The URIMap view is 
provided by CICS Explorer. See Figure 5-1 . 


<|f URI Maps k£2 1^1 Regions % Tasks QQ I5C/MRO Connections 2 Terminals i) 

CNX0211I Context: EPRED. Resource: URIMAP. 6 records collected at Oct 26, 2009 4:00:56 P 

Region Name 

Status Usage 

Referenc... TCP/IPS... 

jEPREDW CHRIS 

✓ ENABLED PIPELINE 

6 

EPREDW EVUCMCIU 

✓ ENABLED SERVER 

2740 EYUCMCIT 

EPREDW UMAPATOM 

v' ENABLED ATOM 

0 

EPRED4 MYURIMap 
EPRED4 STEVE 1 

X DISAB... PIPELINE 
✓ ENABLED SERVER 

0 

0 

EPRED4 STEVE2 

X DISAB... SERVER 

0 STEVE 








< 


1111 


Figure 5-1 URIMap view 
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To show the structured URIMAP information in our sampleView, we implement a 
tree view displaying hierarchical URIMap information that is not available in the 
CICS Explorer provided view. See Figure 5-2. 



,£2 /£ Events □ Properties 

Property 

Value 

0 URIMap 

Name 

EYUCMCIU 

Usage 

SERVER 

Status 

V ENABLED 

Reference Count 

2784 

0 Program 

DFHWUIPG 

Status 

✓ ENABLED 

e TCP/IP Service 

EYUCMCIT 

Ipresolved 

9.12.4.75 

Port 

16001 


Figure 5-2 Tree view for URIMap detailed information 


It is also possible to implement automatic Get and Display functions in the view 
for the following additional related information depending on the selected 
URIMAP USAGE value: 

► If URIMAP USAGE is SERVERIPIPELINEIATOM, the view gets and displays 
TCPIPService instance information. 

► If URIMAP USAGE is SERVER, the view gets and displays Program instance 
information. 

► If URIMAP USAGE is PIPELINE, the view gets and displays Pipeline instance 
information. 

You can show a sampleView from the menu bar by navigating to Window -» 
Show View ->• Other. Then, click record in the URIMap view. The sampleView 
shows the URIMap detailed information. 
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5.1.3 Using our sample code 


All code to get and display the URIMap detailed information is integrated into the 
populatelnformation method for better extensibility. This view has the following 
process steps: 

1. createPartControl method 

- Create the Tree View to display URIMap detailed information, as an initial 
process. 

2. populatelnformation method 

- Integrate a process to get and display target URIMap detailed information. 
This process is done only when the following two conditions are both 
satisfied, because both conditions are required to allow the target to get 
detailed URIMap information. 

• URIMap view is opened 

• One line in the URIMap is selected 

3. selectionListener method 

- The left-click operation in the URIMap view causes this selectionListener 
event. You can invoke populatelnformation here. 

Example 5- 1 Sample code: MySampletreetable View.java 
package my _treetableview. views; 

import helper.FilteredContext; 
import java. net. URL; 

import org .eel i pse . core . runtime . Fi 1 eLocator ; 

import org. eel ipse. core. runtime. I ProgressMoni tor; 

import org. eel ipse. core. runtime. IStatus; 

import org. eel ipse. core. runtime. Path; 

import org. eel ipse. core. runtime. Platform; 

import org. eel ipse. core. runtime. Status; 

import org. eel ipse. core. runtime. jobs. Job; 

import org. eel ipse. j face. resource. ImageDescriptor; 

import org. eel ipse. jface. viewers. ISelection; 

import org.ecl ipse. jface. viewers. StructuredSelect ion; 

import org. eclipse. swt. SWT; 

import org.ecl ipse. swt. graphics. Image; 

import org.ecl ipse. swt. widgets. Composite; 

import org.ecl ipse. swt. widgets. Display; 

import org.ecl ipse. swt. widgets. Tree; 
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import org. eel ipse. swt.widgets.TreeCol umn; 
import org. eel ipse. swt. widgets. Treeltem; 
import org. eel ipse. ui .ISelectionListener; 
import org. eel ipse. ui .IViewSite; 
import org. eel ipse. ui . IWorkbenchPart; 
import org. eel ipse. ui .PartlnitException; 
import org. eel ipse. ui .part.ViewPart; 
import org.osgi .framework. Bundle; 

import com. ibm.cics. core. model .CICSTypes; 

import com. ibm.cics. core. model .Context; 

import com. ibm.cics. core. model . ICPSM ; 

import com. ibm.cics. core. model . IResourcesModel ; 

import com. ibm.cics. core. ui .UlPlugin; 

import com. ibm.cics. model . IAtomServi ce; 

import com. ibm.cics. model . ICICSObject; 

import com. ibm.cics. model .ICICSType; 

import com. ibm.cics. model . ICICSpl ex; 

import com. ibm.cics. model . I Pi pel i ne ; 

import com. ibm.cics. model . I Program; 

import com. ibm.cics. model . ITCPIPServi ce; 

import com. ibm.cics. model .IURIMap; 

import com. ibm.cics. model . IWebServi ce; 

public class MySampletreetableView extends ViewPart { 

private Tree tree; 

private Treeltem i temURIMapUsageKey, itemURIMapTCPIPServiceKey; 

private String uriMapStri ng; 

private ICPSM cpsm; 

private IURIMap iurimap; 

private ITCPIPService itcpipservice; 

private I Pi pel i ne ipipeline; 

private IWebService iwebservice; 

private I Program i program; 

private IAtomService iatomservi ce; 

private Context context; 

private IResourcesModel model; 

// Load images from icons directory 

private Bundle bundle = PI atform.getBundl e(my_treetabl eview. Activator. PLUGIN_ID) ; 

private URL imageEnableURL = FileLocator.find(bundle, new Path( 

"i cons/ENABLED.gi f ") , null); 

private URL imageDi sabl eURL = FileLocator.find(bundle, new Path( 
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"i cons /DISABLED. gi f ") , null); 

private URL imageErrorURL = FileLocator.find(bundle, new Path( 
"icons/Error.gif") , null); 

private Image imageEnable = ImageDescriptor.createFromURL(imageEnableURL) 
.createlmage() ; 

private Image imageDisable = ImageDescriptor.createFromURL(imageDisableURL) 
.createlmage() ; 

private Image imageError = ImageDescriptor.createFromURL(imageErrorURL) 
.createlmage() ; 

private Fi IteredContext fi 1 teredContext; 

QOverride 

public void createPartControl (Composite argO) { 

// tree(table) definition 

tree = new Tree(argO, SWT. BORDER | SWT.FULL_SELECTION) ; 

// add attribution 

tree.setHeaderVisible(true) ; // display header 
tree.setLinesVisible(true) ; // display lines 
// set headers 

String[] cols = { "Property", "Value" }; 
for (int i = 0; i < cols. length; i++) { 

TreeColumn col = new TreeColumn(tree, SWT. LEFT); 
col .setText(col s[i] ) ; 
col .setWidth(200) ; 

} 


/** popul atelnformation 
* @param uriMap **/ 

public void popul ateInformation(final String urimapstri ng) { 
// reserve argument (urimap) 
uriMapString = urimapstri ng; 
if (I0() == true) { 

GUI () ; 

} else { 
ngGUI () ; 

} 


public void connectCPSM() { 

// get CPSM information 

cpsm = (ICPSM) UIP1 ugin.getDefault() .getResourceManager( 
UIP1 ugin.SYSTEM_MANAGER_CONNECTION_ID) ; 
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// get CICSplexes 

ICICSplex[] cicsplexes = cpsm.getCICSplexes(); 

// set scopedContext(CPSM,CPSM) 

context = new Context (cicspl exes [0] .getNameO) ; 

filteredContext = new Fi 1 teredContext (context) ; 

} 

private ICICSObject getCICSObject(ICICSType cicsType, String resourceName) { 
f i 1 teredContext . setFi 1 terVal ues (ci csType . getNameAttri bute () , resourceName) ; 
model = cpsm.getModel (cicsType, filteredContext); 
model .acti vate() ; 

model .maybeFetch(0, model .size()) ; 

return model. size() > 0 ? model. get(0) : null; 


public void getURIMapResource() { 

iurimap = (IURIMap) getCICSObject(CICSTypes .URIMap, uriMapString) ; 

} 

public void getTCPIPServi ceResource() { 

itcpipservice = (ITCPIPService) getCICSObject(CICSTypes .TCPIPServi ce, 
iurimap. getTCPIPService()) ; 

} 


public void getProgramResourceQ { 

iprogram = (IProgram) getCICSObject(CICSTypes. Program, iurimap 
.getProgramQ) ; 

} 


public void getAtomServiceResource() { 

iatomservice = (IAtomService) getCICSObject(CICSTypes.AtomService, 
iurimap. getAtomservi ce()) ; 

} 


public void getPi pel i neResource() { 

ipipeline = (IPipeline) getCICSObject(CICSTypes.Pipel ine, iurimap 
.getPipel ine()) ; 

} 


public void getWebServi ceResource() { 

iwebservice = (IWebService) getCICSObject(CICSTypes.WebService, iurimap 
.getWebService()) ; 

} 


private boolean I0() { 
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connectCPSM() ; 
getURIMapResource() ; 

if (model .size() == 0) { return false; } 
getTCPIPServiceResource() ; 

if (iurimap.getUsage() .toString() == "SERVER") { 
getProgramResourceO ; 

} else if (iurimap.getUsageO .toString() == "CLIENT") { 

// ** no related resources ** 

} else if (iurimap.getUsageO .toString() == "ATOM") { 
getAtomServi ceResource() ; 

} else if (iurimap.getUsageO .toString() == "PIPELINE") { 
getPipel ineResource() ; 
getWebServiceResource() ; 

} 

return true; 


public void GUI () { 

// delete all items 
tree.removeAl 1 () ; 

tree.setHeaderVisible(true) ; // display header 
tree.setLinesVisible(true) ; // display lines 
// URI Maps 

Treeltem itemURIMap = new Treeltem(tree, SWT. NULL); 
itemURIMap. setText(0, "URI Map"); 
itemURIMap. setText(l, ""); 

Treeltem i temURIMapName = new TreeItem(itemURIMap, SWT. NULL); 
itemURIMapName.setText(0, "Name") ; 
itemURIMapName.setText(l, iurimap.getNameO) ; 

Treeltem i temURIMapUsage = new TreeItem(itemURIMap, SWT. NULL); 
itemURIMapUsage.setText(0, "Usage") ; 

itemURIMapUsage.setText(l, iurimap.getUsageO .toStringO) ; 

Treeltem i temURIMapStatus = new TreeItem(itemURIMap, SWT. NULL); 
itemURIMapStatus.setText(0, "Status") ; 

if (iurimap.getStatusO .toStringO == "ENABLED") { 
itemURIMapStatus.setImage(l, imageEnable) ; 

} else if (iurimap.getStatusO -toStringO == "DISABLED") { 
itemURIMapStatus.setImage(l, imageDisable) ; 

} 

i temURIMapStatus. setText(l, iurimap.getStatusO .toStringO) ; 
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Treeltem i temURIMapReferenceCount = new TreeItem(itemURIMap, SWT. NULL); 
i temURIMapReferenceCount.setText(0, "Reference Count"); 
i temURIMapReferenceCount. setText(l, iurimap.getReferenceCount() .toStringO) ; 

i temURIMapUsageKey = new TreeItem(itemURIMap, SWT. NULL); 

if (iurimap.getUsage() .toStringO == "SERVER") { 
itemURIMapUsageKey.setText(0, "Program") ; 
i temURIMapUsageKey. setText(l, i uri map. get Program ()) ; 

} else if (iurimap.getUsage() .toStringO == "CLIENT") { 
itemURIMapUsageKey.setText(0, "Port") ; 

itemURIMapUsageKey.setText(l, i urimap.getPortQ .toStringO) ; 

} else if (iurimap.getUsageO .toStringO == "ATOM") { 
itemURIMapUsageKey.setText(0, "Atomservi ce") ; 
i temURIMapUsageKey. setText(l, iurimap.getAtomserviceO) ; 

} else if (iurimap.getUsageO .toStringO == "PIPELINE") { 
itemURIMapUsageKey.setText(0, "Pipel ine") ; 
itemURIMapUsageKey.setText(l, i urimap.getPi pel ine()) ; 

} 


if (iurimap.getUsageO .toStringO != "CLIENT") { 

itemURIMapTCPIPServiceKey = new Treeltem(i temURIMap, SWT. NULL); 
itemURIMapTCPIPServiceKey. setText(0, "TCP/IP Service"); 
itemURIMapTCPIPServiceKey.setText(l, i urimap.getTCPIPServi ce()) ; 


// if (tcpipserviceModel .size() > 0) { 
if (itcpipservice != null) { 

Treeltem itemTCPIPServicelPResol ved = new Treeltem( 
itemURIMapTCPIPServiceKey, SWT. NULL); 
itemTCPIPServicelPResol ved. setText(0, "I presol ved") ; 
itemTCPIPServicelPResol ved. setText(l, itcpi pservi ce.getlpresol ved()) ; 

Treeltem i temTCPI PServi cePort = new Treeltem( 
itemURIMapTCPIPServiceKey, SWT. NULL); 
i temTCPI PServi cePort. setText(0, "Port") ; 

i temTCPI PServi cePort . setText (1 , itcpi pservi ce. get Port () .toStri ng () ) ; 


// items related with URIMap 
if (iurimap.getUsageO .toStringO == "SERVER") { 
if (i program != null) { 

// Program resource 

Treeltem itemProgramStatus = new TreeItem(itemURIMapUsageKey, SWT. NULL); 
itemProgramStatus.setText(0, "Status") ; 
if (iprogram.getStatusO .toStringO == "ENABLED") { 
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itemProgramStatus.setImage(l, imageEnable) ; 

} else if (i program. getStatusO .toString() == "DISABLED") { 
itemProgramStatus.setImage(l, imageDisable) ; 

} 

itemProgramStatus. setText (1, i program. getStatus () .toStringO) ; 

} 

} else if (iurimap.getUsageO .toStringO == "CLIENT") { 

} else if (iurimap.getUsageO .toStringO == "ATOM") { 
if (iatomservice != null) { 

// Atomservice resource 

Treeltem i temAtomservice = new TreeItem(itemURIMapUsageKey, SWT. NULL); 
i temAtomservice. setText(0, "Atomservice") ; 
i temAtomserv i ce . setT ext ( 1 , " " ) ; 

Treeltem itemAtomserviceEnablestatus = new Treeltem( 
itemAtomservice, SWT. NULL); 
i temAtomservi ceEnabl estatus .setText (0, "Status") ; 
if (iatomservice. getEnabl estatus () .toStringO == "ENABLED") { 
i temAtomservi ceEnabl estatus . set Image ( 1 , imageEnabl e) ; 

} else if (iatomservice. getEnablestatusO -toStringO == "DISABLED") { 
i temAtomservi ceEnabl estatus . set Image ( 1 , imageDi sabl e) ; 

} 

i temAtomservi ceEnabl estatus .setText ( 1 , i atomservi ce 
.getEnablestatusO .toStringO) ; 

} 

} else if (iurimap.getUsageO .toStringO == "PIPELINE") { 
if (ipipeline != null) { 

// Pi pel ine resource 

Treeltem i temPi pel ineStatus = new TreeItem(itemURIMapUsageKey, SWT. NULL); 
i temPi pel ineStatus. setText (0, "Status") ; 
if (ipipel ine. getStatusO .toStringO == "ENABLED") { 
i temPi pel ineStatus. setlmage(l, imageEnable) ; 

} else if (ipipeline. getStatusO -toStringO == "DISABLED") { 
i temPi pel i neStatus . set Image ( 1 , imageDi sabl e) ; 

} 

i temPi pel ineStatus. setText (1, ipipel ine. getStatusO .toStringO) ; 

Treeltem itemURIMapWebService = new TreeItem(itemURIMap, SWT. NULL); 
itemURIMapWebService. setText (0, "WebServi ce") ; 
itemURIMapWebService. setText (1, iurimap.getWebServiceO) ; 

if (iwebservice != null) { 

// Pi pel ine resource 

Treeltem itemWebServiceState = new Treeltem( 
itemURIMapWebService, SWT. NULL); 
itemWebServiceState. setText(0, "State") ; 
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if (iwebservice.getState() .toString() == "ENABLED") { 
itemWebServiceState.setImage(l, imageEnable) ; 

} else if (iwebservice.getStateQ -toStringO == "DISABLED") { 
i temWebServi ceState . set Image ( 1 , imageDi sabl e) ; 

} 

itemWebServiceState.setText(l, ipipel ine.getStatus() .toStringO) ; 

} 

} 

} 

} 

public void ngGUI() { 

// delete all items 
tree.removeAl 1 () ; 

tree.setHeaderVisible(false); // display header 
tree.setLinesVisible(false); // display lines 
// URI Maps 

Treeltem itemURIMap = new Treeltem(tree, SWT. NULL); 
itemURIMap.setImage(0, imageError) ; 
itemURIMap. setText(0, "No URIMap found."); 


OOverride 

public void init(IViewSite site) throws PartlnitException { 
super. init(site); 

s ite. get Page () .addPostSelectionListener(new ISelectionListenerQ { 
QOverride 

public void selectionChanged(IWorkbenchPart argO, 

ISelection selection) { 
if (isVisible() && !selection.isEmpty()) { 

Object firstElement = ((StructuredSelection) selection) 
.getFirstElement() ; 

if (firstElement instanceof IURIMap) { 

final IURIMap urimap2 = (IURIMap) firstElement; 
populateInformation(urimap2.getName()) ; 


} // the end of selectionChanged 
}); // the end of site.getPageQ .addSelectionListener 
} // the end of Override init method 

private boolean isVisible() { return getSite() .getPage() .isPartVisible(this) ; } 

public void setFocus() {} // the end of setFocus method 
} // the end of this class 
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Note: The ngGUI () method is only used for extending the function for new 
textbox and “GO” button in the toolbar. See 5.4, “Extending a toolbar to search 
URIMap information based on user input” on page 125 for more detail 


5.1.4 Running the sample 

We now look at running our sample. 

1 . Run the plug-in as an Eclipse application. 

2. Open the new view (Figure 5-3). 



Figure 5-3 Select sampleView as Eclipse standard operation 
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3. Open the URIMap view (Figure 5-4). 



Figure 5-4 Open URIMap view 
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4. Connect your CICS system using preferences (Figure 5-5). 



Figure 5-5 Connect to CICS System by Preference window 
5. Click this in the URIMap (Figure 5-6). 
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Figure 5-6 URIMap click in the URIMap view 
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6. You can get URIMap detailed information in the new view (Figure 5-7). 
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Figure 5-7 URIMap detailed information display results 


In 5.2, “Using a pop-up menu to access URIMap information” on page 1 10, we 
describe how to further extend and modify based on the new view shown in 
Figure 5-7. 
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5.2 Using a pop-up menu to access URIMap information 


To reach the target URIMap detailed information easier and faster, you can 
modify your plug-ins. The following sections discuss how to implement a pop-up 
menu function in the URIMap view. 

5.2.1 Specification of a new pop-up menu 

The URIMap view is provided by CICS Explorer. You can add a new function to 
show the selected URIMap detailed information more quickly using a new pop-up 
menu. 

1 . Right-click to display pop-up menu list. 

2. Select New Submenu. 

3. Select New Action. 

4. If hidden, open sampleView. 

5. If a URIMap is selected in the URI Maps view, its information is retrieved. 

6. The URIMap information is then displayed in the sampleView. 



Figure 5-8 New action pop-up menu 


110 Extend the CICS Explorer: A Better Way to Manage Your CICS 


5.2.2 Sample code 


Add an extension point, erg. eclipse. ui.popupMenus, to allow for easier 
implementation using the eclipse template. 

1 . Click Add (Figure 5-9) in the Extensions tab to open the Extensions dialog 
box. 


a *My_tree table view ja X 

% Extensions 

AH Extensions ^ g 

Define extensions for this plug-in in the following section. 

| Remove ] 
[ Down ] 


Overview Dependencies Runtime Extensions Extension Points Build MAN 
Figure 5-9 Start adding Extension from Extensions tab 
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2. Choose org.eclipse.ui.popupMenus as the extension point. In the “Available 
templates for pop-up menus” window, and click “Popup Menu” to generate the 
template source code (Figure 5-10). Click Next. 



Figure 5-10 Extension Point Selection dialog window 
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3. Modify the Target Object’s Class into “com.ibm.cics.model.lURIMap” to relate 
this new pop-up menu to the URIMap view (Figure 5-1 1 ). Click Next. 



Figure 5-11 Sample pop-up menu dialog window 
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4. After the template source code and required XML is generated (Figure 5-12), 
modify the source code to meet your needs. 



Figure 5-12 Sample pop-up menu dialog window 

To get and display the detailed URIMap information, modify the run and 

selectionChanged methods in object PopupAction.java. 

► run method 

a. If the view is closed, open the view by double-clicking the 
PopupAction.java object. 

b. Invoke the populatelnformation method in the sampleView with the target 
URIMap name. 

► selectionChanged method 

- You can get URIMap resource information from URIMap view to invoke 
populatelnformation in the sampleView. Example 5-2 on page 115 
shows the PopupAction class after these changes have been applied to 
the generated template class. 
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Example 5-2 Sample code: PopupAction.java 
package my_treetableview. popup. act ions; 
i mport my_treetabl evi ew. vi ews . MySampl etreetabl eVi ew; 

i mport org . eel i pse . j face . acti on . I Act i on ; 

i mport org . eel i pse . j face .viewers . ISel ect i on ; 

i mport org . eel i pse . j face .viewers . StructuredSel ect i on ; 

import org. eclipse. ui .IActionDelegate; 

import org. eclipse. ui .IObjectActionDelegate; 

import org. eclipse. ui .IViewPart; 

import org. eel i pse. ui .IWorkbench; 

import org. eclipse. ui . IWorkbenchPage; 

import org. eel i pse. ui . IWorkbenchPart; 

import org. eel i pse. ui . IWorkbenchWi ndow; 

import org. eclipse. ui .PartlnitException; 

import org. eclipse. ui .PlatformUI; 

import com. ibm.cics. model . IURIMap; 

public class PopupAction implements IObjectActionDelegate { 
private IURIMap uriMap; 

/** Constructor for Actionl. **/ 
public PopupActionQ { super (); } 

/** @see IObjectActionDelegate#setActivePart(IAction, IWorkbenchPart) **/ 
public void setActivePart(IAction action, IWorkbenchPart targetPart) {} 

/** @see IActionDelegate#run(IAction) **/ 
public void run(IAction action) { 

IWorkbench workbench = PI atformUI .getWorkbench() ; 

IWorkbenchWi ndow window = workbench. getActi veWorkbenchWi ndow() ; 

IWorkbenchPage page = wi ndow. getActi vePage() ; 
try { 

IViewPart sampleView = page 

. f i ndVi ew( "my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew") ; 
if (sampleView == null) { 
sampleView = page 

. showVi ew("my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew") ; 

} 

((MySampl etreetabl eView) sampleView) .populatelnformation(uriMap.getNameO) ; 
} catch (PartlnitException e) (e.printStackTrace() ; } 

} 

/** @see IActionDelegate#selectionChanged(IAction, ISelection) **/ 
public void selectionChanged(IAction action, ISelection selection) { 

uriMap = (IURIMap) ((StructuredSelection) selection) .getFirstElement() ; 

} 

} 
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5.2.3 Operation 


1 . To get and show detailed information, right click the target URIMap in the 
URIMap view, and select pop-up menu (Figure 5-13). 



Figure 5-13 Pop-up menu on the URIMap 
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2. If the sampleView is hidden, it appears automatically, and displays the results, 
as shown in Figure 5-14. 



Figure 5-14 Results of pop-up menu 
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5.3 Extending actions of the toolbar and menu bar to 
access URIMap information 


To access the detailed URIMap information more quickly, you can implement the 
view as an actions with an icon button in a toolbar or menu bar. 


5.3.1 Specification of new actions 

In our generated example, you can view the detailed information of a selected 
URIMap by performing the following steps in the workbench perspective: 

1 . Click Sample Menu in the menu bar, or press New in the toolbar, as shown in 
Figure 5-15. 

2. If hidden, the sampleView appears. 

3. The detailed information is fetched for the selected URIMap.. 

4. The sampleView displays the URIMap information as a hierarchical structure. 



Figure 5-15 New actions by new menu bar, and toolbar(icon button) 


Select the target URIMap line in the URIMap view in advance to show the new 
action. If you do not open the URIMap view or select any URIMap in advance, the 
view is shown with no information. 
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5.3.2 Extending actions of the toolbar and menu bar to access 
URIMap information 

Perform the following steps to extend the toolbar and menu bar to access 
URIMap information: 

1 . You can add the views Extension point from the Extensions tab of the project 
as shown in Figure 5-16. Select the views extension and click Add. 


■5^ *Wy_treetabieview 

% Extensions 

All Extensions ja^ [g 

Define extensions for this plug-in in the following section. 

pS 

[ Remove ] 

[ Down ] 
tension Poin 

Figure 5-16 Selecting Add in the Extensions tab 


type filter text 

© o= org.edipse.ui. views 
© ©= org.edipse.ui. perspectiveExtensions 
© «= org.edipse.help.contexts 


Overview Dependences Runtime | Extensions i 
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2. You can choose the “Hello, World” action set template from the Extension 
Wizards tab. This template is suitable for the purpose of extending the icon 
button in the toolbar and menu bar. See Figure 5-17. 



Figure 5-17 Choose “Hello, World” action set template 
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3. Enter Java Package name and Action class, as shown in Figure 5-18. The 
Message Box text is not required so leave it with the default values. 



Figure 5-18 Sample Action Set dialog window 
4. Click Finish to generate the sample source code. 

This sample uses an extension point called org. eclipse. ui.actionSets. To get and 
display URIMap detailed information, you modify the run method in the 
SampleAction. 

1 . Investigate the status of sampleView. If the view is closed, open the view first. 

2. Get the name of the URIMap for which you want more information from the 
URIMap view. 

3. Invoke the popul atelnformation method in the sampleView with the target 
URIMap name. 
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Example 5-3 shows the sample code. 

Example 5-3 Sample code: SampleAction.java 
package my_treetabl evi ew. acti ons ; 
i mport my_treetabl evi ew. vi ews . MySampl etreetabl eVi ew; 

i mport org . eel i pse . j face . acti on . I Act i on ; 

i mport org . eel i pse . j face . vi ewers . ISel ect i on ; 

i mport org . eel i pse . j face .viewers . ISt ructuredSel ecti on ; 

import org. eclipse. ui .IViewPart; 

import org. eel i pse. ui .IWorkbench; 

import org. eclipse. ui . IWorkbenchPage; 

import org. eclipse. ui . IWorkbenchWi ndow; 

import org. eel i pse.ui . IWorkbenchWi ndowActionDel egate; 

import org. eclipse. ui .PartlnitException; 

import org. eclipse. ui .PlatformUI; 

import com. ibm.cics. model . IURIMap; 

/** @see IWorkbenchWi ndowActionDel egate **/ 

public class SampleAction implements IWorkbenchWi ndowActionDel egate { 

/** The constructor. **/ 
public SampleActionQ {} 

/** @see IWorkbenchWi ndowActionDel egate#run **/ 
public void run(IAction action) { 

IWorkbench workbench = PI atformUI .getWorkbench() ; 

IWorkbenchWi ndow window = workbench. getActi veWorkbenchWi ndow() ; 

IWorkbenchPage page = window. getActi vePage() ; 
try { 

IViewPart sampleView = page 

. f i ndVi ew( "my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew") ; 
if (sampleView == null) { 
sampleView = page 

. showVi ew ("my_treetabl evi ew. views. MySampl etreetabl eView") ; 

} 

IViewPart uriMapView = page. findView("com. ibm.cics. sm.ui .views. uriMaps") ; 
if (uriMapView != null) { 

IStructuredSelection structuredSelection = (IStructuredSelection) uriMapView 
.getSite() .getSelectionProvider() .getSelection() ; 
if (IStructuredSelection. isEmptyO) { 

IURIMap uriMap = (IURIMap) structuredSelection.getFirstElement() ; 

( (MySampl etreetabl eView) sampl eVi ew) 

.populatelnformation(uriMap.getNameO) ; 

i 

} 
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} catch (PartlnitException e) { e.printStackTrace() ; } 


} 

/** @see IWorkbenchWindowActionDelegate#dispose **/ 
public void dispose() {} 

/** @see IWorkbenchWindowActionDelegate#init **/ 
public void init(IWorkbenchWindow window) {} 

@0verride 

public void selectionChanged(IAction action, ISelection selection) {} 


5.3.3 Operation 

Now we can test our sample action and look at the deatils for a URIMap. 

1 . Select the target URIMap in the URIMap view, then click Sample Action in 
the toolbar, or select a new action in the menu bar. See Figure 5-19. 



Figure 5-19 Select target URIMap, and select Sample Action menu bar icon 
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2. If the sampleView is hidden, it appears automatically, and displays the results. 
If you click the new toolbar button instead of menu bar icon, you get the same 
results. See Figure 5-20. 



Figure 5-20 Results of new action 


124 Extend the CICS Explorer: A Better Way to Manage Your CICS 


5.4 Extending a toolbar to search URIMap information 
based on user input 


To access URIMap detailed information easier and faster, you can implement a 
textbox and button in the toolbar, like a URIMap filter search box. 


5.4.1 Specification of new textbox and button 

You can use a new function to show the target URIMap detailed information more 
quickly using a textbox and GO button in the toolbar workbench perspective: 

1 . Enter the target URIMap name in the new textbox in the toolbar. 

2. Press the enter key, or click the new GO button. 

3. If hidden, sampleView appears. 

4. Get the specified URIMap detailed information. 

5. Show this in the sampleView as hierarchy structure. 

This function can execute if the URIMap view is hidden, or if no URIMap item has 
been selected in URIMap view. See Figure 5-21. 



Figure 5-21 New textbox and GO button to show target URIMap information 

If the URIMap name does not exist in the URIMap resources, a view is displayed 
with the message No URIMap found. This message handling is implemented by 
noGUI method in the sampleView. For this detailed sample code, see 5.1 .3, 
“Using our sample code” on page 98. 
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5.4.2 Sample code 

To add a text box in the workbench toolbar, perform the following steps: 

1 . Select the views extension point, and click Add in the Extensions tab in the 
project. See Figure 5-22. 


All Extensions ja^ q 

Define extensions for this plug-in in the following section. 


3-0= org.edipse.ui. views 
3 *= org.edipse.ui.perspectiveExtensions 
3 *= org.edipse. help. contexts 


[ Down ] 


Overview Dependenbes Runtime Extensions Extension Poin 


Figure 5-22 Clicking Add in the Extensions tab 

2. Type org. eel ipse. ui .menus in the Extension Point filter, then click Finish. 


C New Extension 
Extension Point Selection 

Select an extension point from those available in the list. 


Extension Points | Extension Wizards 
Extension Point filter: org.edipse.ui.menus| J 
—3 org.edipse.ui. menus 


Figure 5-23 Extension Point Selection dialog window 


126 Extend the CICS Explorer: A Better Way to Manage Your CICS 


3. Right-click org.eclipse.ui. menus, then click New ->• menuContribution. 


© *My_treetab)eview 


% Extensions 

All Extensions ja^ q 

Define extensions for this plug-in in the following section. 


3 o= org.edipse.ui.views 
1 c= org.edipse.ui.perspectiveExtensions 
; o= org.edipse.help. contexts 


Overview Depende 


^ Show Description 
Open Schema 


Extension Det 


Set the properti 
denoted by “ " 


0 menuContribution 




X] widget 
| ' ™ S ^dedarinc 

Points Build MANIFEST. MF plugin. 


Figure 5-24 Add menuContribution to extension point 


4. Enter tool bar : org. eel ipse. ui .main. tool bar in the locationURI textbox. See 
Figure 5-25. 
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5. Right-click toolbar:org. eclipse. ui.main.toolbar and select New Toolbar. 
See Figure 5-26. 


tensions for this plug-in in the following section. 
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Figure 5-26 Add toolbar to new menuContribution 
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6. Right-click the new generated toolbar, then click New ->• Control. See 
Figure 5-27. 
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Figure 5-27 Add new control for textbox 
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7. This new control references the new class for our textbox. Click class to bring 
up a dialog box that prompts you to specify the name of this class. See 
Figure 5-28. 


1% 0 Extension Element Details 

Set the properties of ’control*. Required fields are denoted by '**. 


(menuCo 

olbar) 


dassj t my_treetableview.WorkbenchWindowControlC | Browse, 


Theclass which will be used to create the control that is to 
be hosted in a ToolBar. This must be a subclass of 
WorkbenchWindowControlContribution which provides 
information as to the control's location (i.e. which workbench 
window it's being hosted in and the side of the window that it 
is currently being displayed on. 


Points Build MANIFEST. MF plugin. xml build. properties 


Figure 5-28 Click class link to overwrite new class file 
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8. Specify your new class name in the Name field, then click Finish. See 
Figure 5-29. 



Figure 5-29 Specify new class information 
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The sample code is now generated, you are able to modify the source code for 
your new textbox. 


After the Enter key has been pressed, the selectionListener is generated. To get 
and display the URIMap detailed information based on the specified URIMap 
name in the textbox, you can now modify selectionListener. 

► createControl method 

- Create a textbox instance, and specify the detailed attribute. 

► getText method 

- Get a URIMap name, which is specified in the textbox as String attribute. 
This method is also invoked by the GO button. Integrate this function here. 

► selectionListener method 

a. Invoke getText method to get URIMap name. 

b. Investigate the status of sampleView. If the view is closed, you can open 
the view at first. 

c. Get URIMap resource information from URIMap view to invoke 
populatelnformation in the sampleView. 

The sample code for adding a textbox is shown in Example 5-4. 

Example 5-4 Sample code: WorkbenchWindowControlContribution2_textbox.java 
package my_treetableview; 

import my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew; 

import org.ecl ipse. swt. SWT; 
import org. eel ipse. swt. events. SelectionEvent; 
import org.ecl ipse. swt. events. Select ion Li stener; 
import org.ecl ipse. swt. widgets. Composite; 
import org.ecl ipse. swt. widgets. Control ; 
import org.ecl ipse. swt. widgets. Text; 
import org.ecl ipse. ui . IViewPart; 
import org.ecl ipse. ui . IWorkbench; 
import org.ecl ipse. ui . IWorkbenchPage; 
import org.ecl ipse. ui . IWorkbenchWindow; 
import org.ecl ipse. ui .PartlnitException; 
import org.ecl ipse. ui .PlatformUI; 

import org.ecl ipse. ui . menus. WorkbenchWindowControl Contribution; 

public class WorkbenchWindowControl Contribution2_textbox extends 
WorkbenchWi ndowControl Contri buti on { 

static private Text text; 
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public WorkbenchWindowControlContribution2_textbox() {} 

public WorkbenchWindowControlContribution2_textbox (String id) {super (id); } 

^Override 

protected Control createControl (Composite parent) { 
text = new Text(parent, SWT. SINGLE | SWT. BORDER); 

// specify maximum number of character 
text.setTextLimit(8) ; 

// add listener for the case that enter-key is pushed, 
text .addSel ecti onLi stener (new myLi stener () ) ; 
return text; 


public String getTextboxQ { 

// get the string from the textbox 
String textMessage = text.getText() ; 
textMessage = textMessage. toUpperCase() ; 
return textMessage; 


public class myListener implements SelectionListener { 

^Override 

public void widgetDefaultSelected(SelectionEvent e) { 

// get strings from the textbox by getTextboxQ method 
String textMessage = getTextboxQ; 

// get workbench information and judge whether sampleView is open or not. 
IWorkbench workbench = PlatformUI.getWorkbenchQ; 

IWorkbenchWindow window = workbench. getActiveWorkbenchWindowQ ; 
IWorkbenchPage page = window. getActivePageQ ; 

try { 

IViewPart sampleView = page 

. fi ndVi ew("my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew") ; 

// if sampleView is not opened, invoke showView method, 
if (sampleView == null) { 
sampleView = page 

. showVi ew("my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew") ; 

} 

( (MySampl etreetabl eVi ew) sampl eVi ew) . popul atelnformati on (textMessage) ; 
} catch (PartlnitException el) { el.printStackTraceQ ; } 

} 

^Override 

public void widgetSelected(SelectionEvent e2) {} 

> 

} 
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A GO button control (again with a text entry box) can also be added, this would 
be done in the same way as shown in Figure 5-27 on page 129. The generated 
source code has to be modified to add the GO button. 

Clicking GO generates a SelectionEvent, so we need a SelectionListener that 
gets and displays the URIMap detailed information based on the URIMap name 
specified in the textbox. The changes are as follows: 

► createControl method 

- You can create button instance, and specify detailed attribute. 

► selectionListener method 

a. Invoke getText method in the textbox to get the URIMap name. 

b. Investigate the status of the sampleView. If the view is closed, open the 
view first. 

c. Get the URIMap resource information from URIMap view to invoke 
populatelnformation in the sampleView. 

The sample code for textbox is shown in Example 5-5. 

Example 5-5 Sample code: WorkbenchWindowControlContribution3_button.java 
package my_treetableview; 

import my_treetabl evi ew. vi ews .MySampl etreetabl eVi ew; 

import org. eclipse. swt. SWT; 

import org. eel ipse. swt. events. SelectionEvent; 

import org. eel ipse. swt. events. SelectionListener; 

import org. eel ipse. swt. widgets. Button; 

import org. eel ipse. swt. widgets. Composite; 

import org. eel ipse. swt. widgets. Control ; 

import org. eel ipse. ui .IViewPart; 

import org. eel ipse. ui .IWorkbench; 

import org. eel ipse. ui . IWorkbenchPage; 

import org. eel ipse. ui . IWorkbenchWi ndow; 

import org. eel ipse. ui .PartlnitException; 

import org. eel ipse. ui .PlatformUI; 

import org. eel ipse. ui . menus. WorkbenchWindowControlContribution; 

public class WorkbenchWindowControlContribution3_bottun extends 
WorkbenchWi ndowControl Contri buti on { 

public WorkbenchWindowControlContribution3_bottun() {} 
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public WorkbenchWindowControlContribution3_bottun(String id) { super(id); } 
QOverride 

protected Control createControl (Composite parent) { 

Button button = new Button(parent, SWT. PUSH); 
button. setText("GO") ; 

// add listener for the case that the bottun is pushed, 
button. addSelectionListener (new myListener()) ; 
return button; 

} 

class myListener implements SelectionListener { 

QOverride 

public void widgetDefaultSelected(SelectionEvent e) {} 

QOverride 

public void widgetSelected(SelectionEvent e) { 

WorkbenchWindowControlContribution2_textbox sampled ass = new 
WorkbenchWi ndowControl Contri buti on2_textbox () ; 

String textMessage = sampl eel ass .getTextbox() ; 

// get workbench information and judge whether sampleView is open or not. 
IWorkbench workbench = PlatformUI.getWorkbench() ; 

IWorkbenchWindow window = workbench. getActi veWorkbenchWindow() ; 
IWorkbenchPage page = window. getActi vePage() ; 
try { 

IViewPart sampleView = page 

.findView("my_treetableview.views.MySampletreetableView") ; 

// if sampleView is not opened, invoke showView method, 
if (sampleView == null) { 
sampleView = page 

.showView("my_treetableview.views.MySampletreetableView") ; 

} 


( (MySampl etreetabl eVi ew) sampl eVi ew) . popul atelnformati on (textMessage) ; 
} catch (PartlnitException e2) { e2.printStackTrace() ; } 
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In Example 5-6 the label is also added for a better user interface. In the 
createControl method, you specify detailed attributes for the label. 


Example 5-6 Sample code: WorkbenchWindowControlContribution1_label.java 
package my_treetableview; 

import org. eclipse. swt. SWT; 
import org. eel ipse. swt. widgets. Composite; 
import org. eel ipse. swt. widgets. Control ; 
import org. eel ipse. swt. widgets. Label ; 

import org. eel ipse. ui . menus. WorkbenchWindowControlContribution; 

public class WorkbenchWindowControlContributionl_label extends 
WorkbenchWi ndowControl Contri buti on { 

public WorkbenchWi ndowControl Contri butionl_l abel () {} 

public WorkbenchWi ndowControl Contribution^ abel (String id) { super(id); } 

@0verride 

protected Control createControl (Composite parent) { 

Composite composite = new Composite (parent, SWT. NONE); 

Label label = new Label (composite, SWT. NONE); 

label .setText("URIMap Name:"); 

label .pack() ; 

label .setLocation(0, 3); 

return composite; 



Note: Simple setText method into label makes the text upper location. To 
avoid this, Example 5-6 uses Composite class, and pack method. 
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5.4.3 Operation 


Now we can test our input textbox with GO button and look at the details for a 
URIMap. 

1 . Input the URIMap name in the text box, and hit the return key or click GO. See 
Figure 5-30. 



Figure 5-30 Input target URIMap name, and click GO. 
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2. If sampleView is hidden, it appears automatically, and displays results. See 
Figure 5-31. 



Figure 5-31 Results of new textbox and GO button 


5.5 Background process implementation 

In the above examples where we extend the URIMap view, accessing processes 
to get CICS resource information is done as a synchronous process in Eclipse 
using the main thread. This basically stops Eclipse. You cannot do anything with 
Eclipse in the period, from getting and receiving CICS resource information, to 
completion of drawing them in the sampleView. 

To solve this problem, you can access CICS resource information about a 
separate thread as a background process. This method is described in the 
following sections. 
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5.5.1 Specifications of the background process 


Implementing background processing in your plug-in achieves the following: 

► Access to actual CICS information using another thread in CICS Explorer. 

► Requires drawing a view process as an asynchronous type process, from 
another thread to main thread. Eclipse can do GUI process only in main 
thread, so you can NOT draw view from new another thread. 

► Implement the progress bar into a workbench window, to allow background 
process status percentage visually. We divide the progress into 4 steps, and 
completing each step means 25% progress. 

a. Connect to CICS. 

b. Get URIMap information. 

c. Get TCP/IP service resource information. 

d. Get other information depending on the URIMap USAGE value. 

► Invoke “display.getDefault().asyncExec” in another thread to invoke drawing 
view process to main thread. 

These steps are shown in Figure 5-32. 
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5.5.2 Sample code 


Example 5-7 is the sample code, the key points are how to do the process as a 
job and implement the progress bar. 

To implement this, modify only two methods in the MySampletreetableView.java. 
See Example 5-7 and Example 5-8 for details. 

Example 5-7 Background processing sample code_ 1: populatelnformation method 

public void populatelnformation (final String urimapstri ng) { 

// reserve argument (urimap) 
uriMapString = urimapstring; 

final Job job = new Job("Getting CICS Resource Information") { 

@0verride 

protected IStatus run(final IProgressMonitor monitor) { 

// Do your 10 stuff here 
if (IO(monitor) == true) { 

Display. getDefault() .asyncExec(new RunnableQ { 

public void run() { GUI () ; } // Do your GUI updates here 

}); 

} else { 

Display. getDefault() .asyncExec(new RunnableQ { 

public void run() {ngGUlQ; } // Do your GUI updates here 

}); 

} 

monitor. doneQ ; 
return Status. 0K_STATUS; 

} 


job.scheduleQ ; 

} 


Example 5-8 Background processing sample code_2: IO method 

private boolean IO(IProgressMonitor monitor) { 

monitor.beginTask("Getting CICS Resource Information", 4); 
connectCPSM() ; 

monitor. worked(l) ; // progress monitor + 1 -> 1(25%) 
getURIMapResource() ; 

if (model .size() == 0) { return false; } 

monitor. worked(l) ; // progress monitor + 1 -> 2(50%) 

getTCPIPServiceResource() ; 

monitor. worked(l) ; // progress monitor + 1 -> 3(75%) 
if (iurimap.getUsage() .toString() == "SERVER") { 
getProgramResource() ; 

} else if (iurimap.getUsage() .toString() == "CLIENT") { 
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// ** no related resources ** 

} else if (iurimap.getUsage() .toString() == "ATOM") { 
getAtomServiceResourceQ ; 

} else if (iurimap.getUsage() .toString() == "PIPELINE") { 
getPi pel i neResource() ; 
getWebServiceResource() ; 

} 

monitor. worked(l) ; // progress monitor + 1 -> 4(100%) 
return true; 


5.5.3 Operation 

When you click URIMap view, another thread is generated by the main thread to 
access the CICS resource information. This new thread is used for this access 
process, but the main thread is not used and can continue GUI process. You can 
see the background process progress with the progress bar in the right corner of 
the window, as shown in Figure 5-33. 



Figure 5-33 Background process indicated with progress bar 
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5.6 Summary of extending functions 


All the extending functions described in this chapter can be implemented into one 
plug-in, summarized in Figure 5-34. This diagram helps you understand the 
relationship of all functions, objects, classes, and methods easier. 



Figure 5-34 Summary of extending functions in this chapter 
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5.7 Package extending functions into a plug-in 


When your new plug-in is complete, it can be packaged as a zip file. The zip file 
can then be distributed, or deployed into your environment. The plug-in zip file is 
available for: 

► CICS Explorer, running environment 

► CICS Explorer SDK, developing environment 


5.7.1 Package plug-in into zip file 

This chapter has described many ways in which you can extend functions as a 
plug-in. To make the plug-in an archive file, export your plug-in into a zip file using 
the following steps. 

1 . When you finish developing your plug-in, you can open the new project which 
includes the plug-in function. See Figure 5-35. 


£ Java - My_treetableview/META-INF/MANIFEST.MF - Eclipse SDK 


File Edit Source Refactor Navigate Search Project Run Window Help 


New 
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Figure 5-35 Create new project 
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2. Select Feature Project on the “Select a wizard” window (Figure 5-36) to 
create a feature project. This is an archive plug-in file later. 



Figure 5-36 Select a Feature project 


144 


Extend the CICS Explorer: A Better Way to Manage Your CICS 


3. Enter a name in the “Project name” field (Figure 5-37), then click Next to 
specify more information. 



Figure 5-37 Feature project properties 
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4. In the “Referenced the Plug-ins and Fragments” dialog window (Figure 5-38), 
select and check your plug-in in the plug-ins list. Then, click Finish. 



Figure 5-38 Select referenced plug-in 
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5. When the “Open Associated Perspective?” window (Figure 5-39) displays, 
click Yes. 



Figure 5-39 Open Associated Perspective dialog 
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6. The plug-in development perspective (Figure 5-40) displays for this new 
project. Export the project as an archive file. You can export the project using 
Export Wizard which is launched from Overview tab. 



Figure 5-40 Start Export Wizard to export the feature project 
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7. In the Deployable features window, confirm selected features, and specify the 
zip file name and target directory by clicking Browse. Then click Finish 
(Figure 5-41). 



Figure 5-4 1 Select Available Features and specify Archive file name 

The Export Features window shows the progress of the export. This window 
disappears automatically. 

8. After you have archived your plug-in to an archive file, this zip file is 
deployable to both CICS Explorer (as running environment) and CICS 
Explorer SDK (as developing environment). 
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5.7.2 Deploying plug-in to CICS Explorer 


The following procedure details how to deploy your plug-in archive file to a CICS 
Explorer running environment. 

1 . Start CICS Explorer, which is installed into your environment. 

2. Select Help Software Updates on the menu bar (Figure 5-42). 
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Figure 5-42 Select Help -> Software Updates on the menu bar 
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3. Click Add Site to specify plug-in archive file and file path (Figure 5-43). 



Figure 5-43 Push “Add Site’’ button to specify the plug-in 
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4. Click Archive to specify the plug-in location as file path and archive file 
(Figure 5-44). 



Figure 5-44 Click Archive to specify plug-in archive file 

5. Select your previously created plug-in archive file (Figure 5-45). 



Figure 5-45 Select zip file 
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6. Confirm location information and click OK (Figure 5-46). 



Figure 5-46 Click OK to proceed 
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The deployable plug-in name is shown on the Available Software tab 
(Figure 5-47). 



Figure 5-47 Plug-in name is shown 
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7. Select the plug-in you want to deploy, and click Install (Figure 5-48). 



Figure 5-48 Select plug-in 

The Progress Information window shows progress of the export. This window 
disappears automatically. 
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8. Confirm whether the selected plug-in is the one you want to deploy in the 
“Install” window (Figure 5-49). If correct, click Finish to start install process. 



Figure 5-49 Confirm plug-in to be installed 

The Install window shows installation progress. This window disappears 
automatically. 

9. Restart CICS Explorer to make the installation effective. Click Yes in the 
Software Updates window (Figure 5-50). 



Figure 5-50 CICS Explorer restart confirmation 
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This completes the deployment of your plug-in into the CICS Explorer 
perspective (Figure 5-51). You can now use the plug-in function in the CICS 
Explorer. 



Figure 5-5 1 Plug-in deployed CICS Explorer perspective 
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Part 4 


Integrating CICS 
Explorer with other 
Eclipse Components 


In this part we write a small collection of plug-ins that display data from an 
OMEGAMON server. We also describe the necessary steps to create an CICS 
Explorer plug-in that allows you to set CICS trace levels dynamically for each 
trace component, similar to the functionality provided by the CICS CETR 
transaction. 

Finally we show you how to extend the functionality provided by the Operations 
view of the CICS Explorer, to implement a CEBR-like interface which, when you 
have right-clicked a TS queue, allows you to view the contents of that queue. 


© Copyright IBM Corp. 2010. All rights reserved. 
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6 


Combining OMEGAMON 
data with CICS Explorer 


In this chapter we write a small collection of plug-ins that display data from an 
OMEGAMON server. Although this chapter is aimed specifically at displaying 
OMEGAMON data, many of the techniques and code samples can be re-used 
with minimal modifications when accessing data from other products. 

First we briefly describe OMEGAMON and the Web services interface that we 
are using to access the data. We then create a simple plug-in to fetch data from 
the Web services interface and parse it to find the interesting information. 

Next, we create several simple plug-ins that display data that has been fetched 
from OMEGAMON. 

Finally, we add processing to drive an OMEGAMON plug-in to display the 
OMEGAMON region overview report for a CICS region when that region is 
selected in the CICS Explorer. 


© Copyright IBM Corp. 2010. All rights reserved. 
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6.1 Environment and configuration 

We used the following software levels for this section of this book, in addition to 

those specified earlier for the CICS Explorer environment: 

► IBM Tivoli Monitoring version 6.2 (minimum version 6.1 required for the SOAP 
interface 

► OMEGAMONXE for CICS version 4.1 

► For the examples of interaction between CICS Explorer and OMEGAMON we 
required CICS systems that were both monitored by OMEGAMON for CICS 
and managed by CPSM. We used CICS TS version 3.2 regions for this, but 
earlier or later versions work equally well. 


6.2 Introduction to OMEGAMON 


OMEGAMON XE for CICS on z/OS is a complete monitoring solution that 
enables you to monitor and manage complex CICS systems by addressing 
potential problems quickly. 

OMEGAMON XE for CICS is part of the IBM Tivoli Monitoring (ITM) architecture 
and uses the Tivoli Enterprise Portal (TEP) as its user interface. The TEP is a 
highly customizable Java application that can either be run as a desktop 
application or run as an applet in a browser. Through this interface, you can 
monitor all your CICS regions, and the other systems in your enterprise. 

Figure 6-1 on page 163 shows a simplified ITM architecture working in 
conjunction with the CICS Explorer. The CICS regions are monitored by the 
CICS agents, which pass their data along to the Tivoli Enterprise Monitoring 
Server (TEMS). The data is presented to the user through the TEP client, which 
extracts its data from the TEMS through the Tivoli Enterprise Portal Server 
(TEPS). The CICS Explorer extracts its data from CICS through the CMCI 
interface. There is also the option of the CICS Explorer accessing CICS data 
through CPSM, but that is not shown here, because it complicates the diagram 
further. 

The TEP, however, is not an Eclipse application, and as such, does not integrate 
readily with the CICS Explorer. The ITM architecture also provides a Web 
services interface. This chapter discusses how we used this interface to access 
OMEGAMON data in an Eclipse plug-in by sending and receiving SOAP 
messages. Accessing OMEGAMON data in an Eclipse plug-in makes it easier to 
use these complementary CICS tools together. 
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6.3 The Tivoli Enterprise Web Services interface 

Tivoli Enterprise Web Services is an open interface into Tivoli Monitoring and 
although it provides access to data from most Tivoli monitoring applications, we 
are concerned solely with looking at CICS data. 

Tivoli Enterprise Web Services implements client/server architecture. The client 
sends SOAP requests to the Tivoli Monitoring SOAP server, which is part of the 
TEMS. The server receives and processes the SOAP requests on behalf of the 
client, and returns with an appropriate response. Although there is much that can 
be achieved through the Tivoli Web Services interface, this plug-in only uses the 
CT_Get command, which allows us to request OMEGAMON data from server. 

This plug-in communicates with the TEMS through the TEMS SOAP interface, 
which must be configured as described in the IBM Tivoli Monitoring: 
Administrator’s Guide. We do not include support for connections to the SOAP 
interface over secure (SSL) connections in this chapter. 
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6.3.1 Connecting to the TEMS SOAP interface with the Web client 

Note the host name (or IP address) and port number for the SOAP interface, as 
this is required later. When we point a browser at the host system containing the 
TEMS (and port 1920), we see a view similar to that shown in Figure 6-2. 



Figure 6-2 ITM Service Index list 
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When we click one of the listed IBM Tivoli Monitoring Web Services we see the 
Tivoli generic SOAP client, as shown in Figure 6-3. 

We can use this simple Web client to test the TEMS SOAP interface and to try 
out commands that we might like to implement in the Eclipse plug-ins that we are 
implementing. 


J Address http://winmvs2c.hurslev.fam.com: 13277Atxxt]ess:tems 3 Q Go 

CT_SOAP Generic SOAP Client 

Note: Have the Access data sources across domains enabled in IE's security settings. This setting is disabled 
by default. If disabled, you'll get an access denied error when pressing the Call Method button. 


Enter your SOAP Request here: Your Soap Response Payload: 


| Enter SOAP request details manually below or select 3 

Endpoint: 

I I 

Interface: 

|CT_SOAP 

Method: 


|CT_Get 

Payload (XML): 


<CT_Getxuserid: 

►sysadmin</useridxpassworc 


gedSystemNameC/i 

:argetx/CT_Get > 3 

ii 


Make SOAP Request 


Figure 6-3 ITM Generic SOAP client 
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We can issue a simple query against the TEMS server’s SOAP interface using 
the Web client. We shall issue a request for the Managed System List. This is a 
list of the Tivoli monitoring systems and the systems they are monitoring (such as 
your CICS regions). The Web client offers this query as one of its predefined 
queries. The list of queries is shown in Figure 6-4. 


Enter your SOAP Request here: 


http://localhost:1920///cms/soap (Get Object CT Method ) 3 

Enter SOAP request details manually below or select 


http://localhost:1920///cms/soap (Alert CT Method ) 
http://localhost:1920///cms/soap (Acknowledge CT Method ) 
http://localhost:1920///cms/soap (Reset CT Method ) 
http://localhost:1920///cms/soap (Resurface CT Method ) 
http://localhost:1920///cms/soap (WTO CT Method ) 
http://localhost:1920///cms/soap (Alert Item CT Method ) 
http://localhost:1920///cms/soap (Deactivate CT Method ) 
http://localhost:1920///cms/soap (Activate CT Method _ 

Figure 6-4 List of queries available in the SOAP Web client 


We select the option for the Get Object CT Method (CT_GET), and this fills in the 
other entry text boxes for us. The endpoint text box gets filled in with the default 
URL for a SOAP server running on the local machine. 

As we are not connecting to a server on the local machine, we have to overwrite 
this value with the host and port from the browser’s address bar. We then look at 
the Payload text box, which contains the message that is sent to the SOAP sever. 
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Because the TEMS server to which we are connecting does not have security 
enabled, we do not have to change the user ID from “sysadmin”, or specify a 
password. This gives us a request ready to be issued, as shown in Figure 6-5. 


j Address 1 g) http://wnmvs2c.hursley.ibm.com: 13277/gburgess:tems 


Enter your SOAP Request here: 


|http://localhost:1920///cms/soap (Get Object CT Method ) ~^j 

Endpoint: 

|http://winmvs2c.hursley.ibm.com:13277///cms/soap 

Interface: 

|CT_SOAP 

Method: 

|CT_Get 

Payload (XML): 

<CT Getxu3eri.d>svsadrain</useridXpasswordx/pas ■*! 
3wordxobject>ManagedSy3Cem</ob jeccxtargeoMana 
gedSystemName</targetx/CT_Get:> 

zl 


Make SOAP Request 

Figure 6-5 Web client Managed System List request 

Click Make SOAP Request and the client issues the SOAP request to the server 
and displays the response. The response can be quite large, depending on how 
many Tivoli monitoring systems you have and how many systems they are 
monitoring. The start of our results are shown in Figure 6-6 on page 168. 

We can see in these results that our request was successful as the response 
contains the text SOAP-CHK: Success near the start of the message, and we have a 
long response made up of numerous XML fields containing information about our 
managed systems. 

The Web client does not parse this XML into a more meaningful format, such as 
a table for us, but we write suitable parsing and formatting code as part of our 
Eclipse plug-ins. 
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Tip: The SOAP Web client can be a useful tool when you are trying to test a 
new request against the SOAP interface, as it can be invoked from a browser 
without having to write any code. You can see exactly what response is 
returned from the server. 



Figure 6-6 Extract from the SOAP Web client response 

We have issued a simple request against the SOAP interface, we can be 
confident that our SOAP interface is working, and that we know exactly which 
host name and port on which it is listening for requests. Now we can move on to 
writing an Eclipse plug-in that issues the same request, and build upon that 
plug-in. 
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6.4 A simple OMEGAMON SOAP interface plug-in 

We start with a simple plug-in that can connect to the TEMS SOAP interface, 
issue a request, and receive the returned SOAP data. We then add the ability to 
parse the returned data. 

We request the Managed System List. This is a list of all the systems that are 
known to the Tivoli monitoring system, and the Tivoli servers that make up the 
monitoring architecture. The returned data includes: 

► The name of the monitored system 

► An indicator of whether the system is online or offline 

► A product code identifier that identifies the Tivoli monitoring product 

The returned list includes products other than CICS if you have other Tivoli 
monitoring products installed 

The plug-in is written with a JUnit (v3) test harness to allow us to build up the 
code in small chunks, explaining and testing each as we go. This plug-in initially 
does the minimum required to issue a request to the SOAP server and receive a 
response. We then build on this functionality. 

First, we create the plug-in project. We can create the plug-in using the plug-in 
wizard (Navigate to File — > New ->• project and select Plug-in project in the 
New Project dialog box). We name the plug-in 0MEGAM0N_S0AP and accept the 
defaults, with one exception. Clear the This plug-in will make contributions to 
the Ul option, and we do not use a template for the plug-in. This plug-in does not 
make any contributions to the user interface, because its role is to capture data 
that is presented to the user by other plug-ins. 
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After we have created the plug-in project, the workspace looks something like 
Figure 6-7. 


B Package Explor sTX jgj'. Ptug-<ns ° Ell OMEGAMON_SOAP E3~\ 
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0 • 0 Activator .java 
B & META-INF 
1 [n} build. properties 


0 Activate this plug-in when one of its classes is loaded 
□ This plug-in is a singleton 


omegamon_soap. Activator 


jn environments required to run this plug-in. 

| Add... 


Figure 6-7 Newly created OMEGAMON_SOAP plug-in 


We now need to create the class that fetches the data from the Web services 
interface. We create a new class Soaplnterface in the ‘omegamon_soap’ 
package. See Example 6-1 . 

Example 6-1 Soaplnterface class listing 
package omegamon_soap; 

import java.io.BufferedReader; 
import java.io.InputStream; 
i mport j ava . i o . InputStreamReader ; 
i mport j ava . net . Connect Except i on ; 
import java.net.HttpURLConnection; 
i mport j ava . net . Mai formedURLExcept i on ; 
import java. net. SocketException; 
import java. net. URL; 

public class Soaplnterface { 

public static final String MANAGED_SYSTEM_LIST_REQUEST = 
"<object>ManagedSystem</object><target>ManagedSystemName</target>"; 

//(l) 

private String ctGet; 
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private URL url ; 


public SoapInterface(String hostName, int port, String userid, String 
password) { //( 2) 

if (password == null) { 
password = 

} 

ctGet = "<CT_Get><userid>" + userid + "</userid><password>" + 
password + "</password>"; 

try { 

this. url = new URL("http://" + hostName + + port + 

"///cms/soap") ; 

} 

catch (Mai formedURLException e) { 
e.printStackTrace() ; 

} 

} 


/** 

* issue a request for some data from the SOAP interface and return 

* the response 

* Oparam payload the request to be issued 

* Oparam url the url of the SOAP interface we wish to connect to 

* Oreturn the results of the request 
*/ 

public String getData (String request) { 

/ / (3) 

String payload = ctGet + request + "</CT_Get>"; 

HttpURLConnection url Connection = null; 
try { 

// create a HTTP connection configure it for a SOAP request 
urlConnection = (HttpURLConnection) url .openConnectionQ ; 
url Connect ion. set RequestMet hod ("POST") ; 
url Connecti on . setDoOutput (true) ; 

// issue our request 

url Connecti on .getOutputStream() .wri te (payl oad .getBytes () ) ; 

// ensure the request has been issued and close the output stream 
urlConnection. getOutputStream() .flush() ; 
urlConnection. getOutputStream() .close() ; 

// read the response from the SOAP interface 

InputStream in = urlConnection. getlnputStreamQ ; 

BufferedReader reader = new BufferedReader(new 
InputStreamReader(in)) ; 

StringBuffer result = new Stri ngBufferQ ; 


Chapter 6. Combining OMEGAMON data with CICS Explorer 171 



String line; 
do { 

line = reader. readLi ne() ; 
if (line != null) { 
result. append(line); 

} 

} while ( line != null ); 

return result. toStringO ; 

} 

catch (ConnectException e) { 

System. out. println("Connect exception - check host and port"); 
e.printStackTraceQ ; 
return nul 1 ; 

} 

catch (SocketException e) { 

System. out. println("Socket exception- check host and port"); 
e.printStackTraceQ ; 
return nul 1 ; 

} 

catch (Exception e) 

{ 

System. out . pri ntl n ( "Other except i on . ") ; 
e.printStackTraceQ ; 
return nul 1 ; 

} 

final ly 

{ 

// always clean up before we leave 
if (url Connection != null) { 
urlConnection.disconnectQ ; 



} 


} 


Notes on Example 6-1 on page 170: 

► The static final String MANAGED_SYSTEM_LIST_REQUEST contains a 
simple request for a list of managed systems from the Web services interface 

► The constructor builds up the URL for the Web service and constructs a 
‘CT_GET’ request String that can be combined with a request for data to 
drive the Web service. 

► The getDataQ.) method constructs a request for data, sends it to the Web 
service, and returns the reply from the Web service. This reply is in the form 
of an XML String. 
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We now want to drive this code to ensure that it works. We do this with a JUnit 
test class.We create the JUnit test class in the omegamon_soap_tests package. 
This is shown in Example 6-2. 

Example 6-2 SoapInterfaceTester class listing 

/* Get the value of ARRAY_VAL. Note: arraylndex starts at 0 */ 
package omegamon_soap_tests; 

import omegamon_soap.SoapInterface; 
import junit. framework. Test; 
import junit. framework. TestCase; 
import junit. framework.TestSuite; 

public class SoapInterfaceTester extends TestCase { 

// useful test data 

/** 

* create a test suite for the tests in this class 

* Oreturn the test suite 
*/ 

public static Test suite() { 

return new TestSui te(SoapInterfaceTester.cl ass) ; 

} 


OOverride 

protected void setUpO throws Exception { 

// TODO Auto-generated method stub 
super. setUpO ; 

} 

public void testNothingO { 

} 

public void testSoapRequestO { 

Soaplnterface soaplnterface = new SoapInterface("winmvs2c. hursley.ibm.com", 

47587, "sysadmin", 

String result = soaplnterface. getData(SoapInterface. MANAGED_SYSTEM_LIST_REQUEST) ; 
assertNotNul 1 ("Result should not be null", result); 

assertTrue("Result length should be greater than zero", result. length() > 0); 
assertTrue("SOAP request failed, result {" + result + "}", 
result. contains ("<S0AP-CHK: Success") ) ; 

} 


OOverride 


protected void tearDown() throws Exception { 
// TODO Auto-generated method stub 
super. tearDown() ; 
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You have to change the host name, port, user ID and password to match those 
for your system. These values are those used in 6.3.1 , “Connecting to the TEMS 
SOAP interface with the Web client” on page 164. 

This test code merely creates an instance of the Soaplnterface class and issues 
a request for a managed system list. The returned data is checked to ensure that 
something is returned, and that the returned data includes the 
<SOAP-CHK:Success string. If this string is found, the request has been 
processed successfully. 

6.4.1 Parsing the returned data 

Now that we have data being returned from OMEGAMON, we need to parse it to 
find the interesting data, and to convert it into a more useful format. Because we 
are reading the complete SOAP reply before processing it, we can use the DOM 
SOAP parser, which simplifies the parsing code. 

The XML parsing code is contained in a new SoapXMLParser class in the 
omgamon_soap package. The XML parsing reuses a single DocumentBuilder 
instance, so this can be declared as a static instance field and initialized in a 
static code block. This means that the SoapXMLParser class starts off looking 
like the listing shown in Example 6-3. 

Example 6-3 SoapXMLParser static code 
public class SoapXMLParser { 

// the DocumentBuilder will enable us to parse the XML easily 
private static DocumentBuilder documentBuilder; 

/** 

* Create the document builder that will be used to parse the SOAP data 
*/ 

static { 

// Create the factory that will be used to create the document builder 
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstanceO ; 
try { 

// and create the document builder 
documentBuilder = dbf.newDocumentBuilder() ; 

} 

catch (ParserConfigurationException e) { 

System. out. println(e) ; 
e.printStackTraceQ ; 

} 

} 

} 
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Note: We are reusing a single DocumentBuilder instance to parse all our 
XML. This might not be a good idea if you expect to be fetching data on 
multiple threads that might overlap, and would be bad if you wanted to do any 
parsing outside of the constructor call as there might be a clash with another 
instance using the same DocumentBuilder 

The parser extracts all the interesting data from the XML when the constructor is 
invoked, so we do not need instance fields to store the XML, but we do need 
instance fields to store the interesting information extracted from the XML. We 
add the following instance fields to the class: 

// the parsed data 
private Stri ng [] [] dataTable; 
private String[] columnNames; 
private int rowCount; 

Next, we need the constructor that accepts XML to be parsed as its input, and 
initialize the instance fields with data extracted from the XML. This method is 
shown in Example 6-4. 

Example 6-4 SoapXMLParser constructor 

* parse the passed String of XML data 

* Qparam xml the data to be parsed 

* Qthrows Exception thrown if we fail to parse the passed data 
*/ 

public SoapXMLParser (String xml) throws Exception { 

NodeList nodeList = null; 
try { 

// load the XML String into an XML Document 
Document document = documentBuilder.parse( 
new ByteArrayInputStream(xml .getBytes("UTF-8"))) ; 

// first find the root of the XML document 
Element root = document. getDocumentElement() ; 

// extract the interesting data as a list of rows 
nodeList = root.getElementsByTagName("ROW") ; 

} 

catch (DOMException dom) { 

System. out . pri ntl n (dom.getMessage () ) ; 
dom.printStackTrace() ; 
throw dom; 

} 
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catch (IOException ioe) { 

System.out.println(ioe) ; 
ioe.printStackTrace() ; 
throw ioe; 

} 

// now construct a table from the XML document 
rowCount = nodeList.getLength(); 
if (rowCount > 0) { 

dataTable = new Stri ng [rowCount] [] ; 
for (int i = 0; i < rowCount; i++) { 

Node rowNode = nodeList . i tem(i ) ; 
dataTable[i] = getRowValues (rowNode); 

} 

// extract the column headers 


columnNames = getRowFiel dNames (nodeLi st .i tem(0)) ; 



This method introduces compile errors as we have not yet added the methods it 
calls. One of the advantages of parsing the XML in the constructor is that we 
know that if any problems are found, then we are not left with an invalid instance 
of the class. The constructor either completes successfully with valid data or 
throws an Exception. Extracting the data we want from the XML is implemented 
in two methods: 

► getRowValues (...) 

► getRowFiel dNames (...) 

These methods are shown in Example 6-5. 

Example 6-5 XML data extraction methods 
/** 

* return the passed node's values as an array of Strings 

* @param node the Node to be processed 

* Qreturn a String[] containing the Node's values 
*/ 

private static String[] getRowVal ues (Node node) { 

NodeList children = node.getChi 1 dNodes () ; 

String [] values = null ; 

if (children != null && children. getLengthQ > 0) { 
int childCount = chi 1 dren. getLengthQ ; 
values = new String[childCount] ; 

for (int i =0; i < childCount; i++) { 
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Node childNode = chi ldren.item(i) ; 

Text valueNode = (Text) 
childNode. get Fi rstChi 1 d () ; 

if (valueNode != null) { 

values[i] = val ueNode.getNodeVal ue() ; 

} 


} 


} 


return values; 


* return the names of the nodes that make up the passed row. 

* Effectively, these are the column headers for a table containing 
this row. 

* @param row the row from which to extract the names 

* Qreturn a list of names, or null if the row has no elements 
*/ 

private String [] getRowFieldNames(Node row) { 

NodeList children = row.getChi ldNodesQ ; 
if (children != null && children. getLengthQ > 0) { 
int childCount = chi 1 dren. getLengthQ ; 

String[] values = new String[childCount] ; 
for (int i = 0; i < childCount; i++) { 

Node child = chi 1 dren. i tem(i ) ; 
values[i] = child. getNodeName() ; 

} 

return values; 

} 

else { 

return nul 1 ; 


} 


These two methods are quite similar, which is unsurprising as they both walk 
through the XML document looking for fields of interest. There is other data in the 
returned SOAP message, such as the data type of the returned data, but we do 
not extract that data here. These plug-ins treat all returned data as strings. If we 
were to add code that checks the data types, then we could implement better 
formatting of the returned data, such as digit grouping for numbers and display of 
timestamps as date-times rather than long strings of digits. 
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Finally, we need getter methods to expose the parsed data to any callers. These 

are shown in Example 6-6. There is no need for setter methods, as these fields 

are initialized in calls from the constructor. 

Example 6-6 SoapXMLParser getter methods 

public Stri ng [] [] getDataTabl e() { 
return dataTable; 

} 

public int getRowCountQ { 
return rowCount; 

} 

public String[] getCol umnNames () { 
return col umnNames; 

} 


In the writing of this parsing code, we wrote unit test code. This code was 
implemented as another JUnit test class, as shown in <REF 
SoapXMLParserTester class>. The test data (field testDatal) was copied from 
the returned data in a request issued using the SOAP Web client, as described in 
Example 6-7. 

Example 6-7 SoapXMLParserTester class 
package omegamon_soap_tests; 

import omegamon_soap. SoapXMLParser; 
import junit.framework.TestCase; 

public class SoapXMLParserTester extends TestCase { 

// useful test data 
private String testDatal 

= "<?xml version=\"1.0\" encodi ng=\"UTF-8\"?><S0AP-ENV: Envel ope " + 
"xml ns:SOAP-ENV=\"http://schemas.xml soap.org/soap/envel ope/\" " + 
"SOAP- ENV : encodi ngStyle=\" http: //schemas. xml soap.org/soap/" + 

"encodi ng/\"> <SOAP-ENV:Body><SOAP-CHK:Success xml ns :SOAP-CHK " + 

"= \"http://soaptestl/soaptest/\" xmlns=\"urn:candle-soap:" + 

"attri butes\"><TABLE name=\"04SRV. ISITSTSH\"><OBJECT>" + 

"04SRV. ISITSTSH</OBJECT><DATA>" + 
"<R0W><HSITNAME>KS3_Vol_Fragment_Index_Cri ti cal " + 
"</HSITNAME><HNODE>GBURGESS</HNODE><ATOMIZE>" + 
"</AT0MIZE><HGBLTMSTMP>1090906205846000</HGBLTMSTMP>" + 
"<H0RIGINN0DE>0MEGTMS4:MV2C:ST0RAGE</H0RIGINN0DE>" + 
"<PATHNAME></PATHNAME><TYPE dt=\"number\">0</TYPE></R0W>" + 
"<R0W><HSITNAME>KS3_LCU_I0_Rate_Sec_Warning</HSITNAME>" + 
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"<HNODE>GBURGESS</HNODE><ATOMIZEx/ATOMIZE><HGBLTMS"+ 

" TMP>109092420 134500 1</HGBLTMSTMP><H0RIG I NN0DE>0MEGTMS4 : "+ 
"MV2C:ST0RAGE</H0RIGINN0DE><PATHNAME></PATHNAME><TYPE" + 

" dt=\"number\">0</TYPE></R0W></DATA></TABLE>" + 

"</S0AP-CHK: Successx/SOAP-ENV : Body></SOAP-ENV : Envel ope>" ; 

public void testConstructor() { 
try { 

SoapXMLParser parserl = new SoapXMLParser(testDatal) ; 
assertNotNul 1 ("Nul 1 parser", parserl); 
assertEquals("Incorrect row count. Expected 2. Found " + 
parserl. getRowCount() , 2, parserl. getRowCountQ) ; 

String[][] dataTable = parserl .getDataTabl e() ; 
assertNotNul 1 ("Nul 1 data table", dataTable); 
assertEquals("Incorrect table row count. Expected 2. Found " + 
dataTable. length, 2, dataTabl e. 1 ength) ; 

String[] firstRow = dataTable[0] ; 
assertNotNul 1 ("Nul 1 First Row", firstRow); 
assertEquals("Incorrect column count. Expected 7. Found " 

+ firstRow. length, 7, fi rstRow. 1 ength) ; 

String [] col umnHeaders = parserl .getCol umnNames () ; 
assertNotNul 1 ("Nul 1 column headers", col umnHeaders) ; 
assertEquals("Incorrect column count. Expected 9. Found " 

+ col umnHeaders. length, firstRow. length, 
col umnHeaders . 1 ength) ; 


} 

catch (Exception e) { 
e.printStackTrace() ; 

} 


The next section uses this parser with real data returned from the SOAP 
interface to provide suitable data to be displayed in tables in plug-in views. 
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6.4.2 Exposing the plug-in’s functions 


Now that we have a plug-in that can retrieve OMEGAMON data, we need to 
make this functionality available to other plug-ins. In production code, we create a 
package containing just the functions that we want to expose, but here we export 
the package containing all of our interesting code, the omegamon_soap 
package. 

Usually when you want to export a package in a plug-in to be used by other 
plug-ins, you open the plugin. xml file in the plug-in development perspective 
and add the package to the exported packages section on the Runtime tab. The 
options that we selected when we created this plug-in using the wizard meant 
that we did not get a plugin. xml file created for us, so we have to use a slightly 
different approach. In the plug-ins view, double-click the OMEGAMON_SOAP 
plug-in to bring up the OMEGAMON_SOAP plug-in’s properties. Click the 
Runtime tab and click Add in the exported packages section. This brings up the 
exported packages dialog panel, shown in Figure 6-8. 



Figure 6-8 Exported Packages dialog menu 


180 Extend the CICS Explorer: A Better Way to Manage Your CICS 



Select the omegamon_soap package and click OK. The package is then added 
to the list of exported packages. See Figure 6-9. 



We have made all the code in the omegamon_soap package available to other 
plug-ins (subject to the usual Java code visibility restrictions). Now we can write 
code in other plug-ins that calls the public methods in these classes. 
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6.5 Displaying the OMEGAMON Managed System List 


Now that we have a plug-in that retrieves data, we need to present that data in an 
Eclipse view. Our first view displays the Managed System List. 


6.5.1 Creating the Managed System List plug-in 

We need a new plug-in to display the data, so we start with the new plug-in 
wizard (Navigate to File -» New ->• project and select Plug-in project in the 
New Project dialog box). Name the plug-in ManagedSystemList and accept the 
defaults on the first two panels. Ensure that the This plug-in will make 
contributions to the Ul check box is selected. On the third panel, create the 
plug-in using a template, and select plug-in with a view, as shown in 
Figure 6-10. 



Figure 6- 1 0 Select plug-in with a view 
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We are creating other visual plug-ins, so it is a good idea to group them so that 
they can be found together when a user selects the menu option Window -> 
Show View. We create our own category for these views, called OMEGAMON. 
We achieve this on the next panel, by overriding several of the default names. We 
also select a table viewer as the type of viewer that is added to the view, as 
shown in Figure 6-1 1 . 



Figure 6-11 Managed System List Main view settings dialog 

Click Finish to complete the creation of the sample plug-in that we use as the 
basis for our view.The wizard has created a plug-in project for us with two 
packages, each containing one class. 
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We need to modify the ManagedSystemListView class, but before we start 
modifying it, we can run it in its current formlf. We invoke run (From the Run 
menu or the Run icon, select Run Eclipse Application. Then launch another 
Eclipse instance. In this instance, navigate to Window Show View Other. 
This brings up the “Show View” dialog box, shown in Figure 6-12. 



Figure 6-12 Show view (ManagedSystemList) dialog 

The views listed in your dialog box might vary a little, depending on what plug-ins 
you have been writing or have imported into your Eclipse environment. Select 
ManagedSystemList View and click OK. This adds a new view to your Eclipse 
workspace that looks like Figure 6-13. 



Figure 6-13 Sample ManagedSystemList view before code changes 

We can see that the plug-in view generated by the wizard already works and 
displays sample data. We just need to change the code to display our Managed 
System List as returned by the SOAP interface. 
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A brief inspection of the generated code is useful at this time. There are several 
key components in the code that we are modifying so they are worth mentioning 
at this time: 

► This view uses a TableViewer instance to display its data. 

► The data that is displayed by the table is provided by the ViewContentProvider 
inner class. 

► The presentation of the data in the table is handled by the ViewLabelProvider 
inner class. 

► Sorting of the data in the class is implemented in the NameSorter inner class 
(which currently has an empty implementation). 

► The createPartControl (...) method creates all the required objects and 
connects them to each-other. 

The generated code also provides dummy implementations of context menus 
and toolbar icons and dummy actions to be invoked from the toolbar and menu 
options. 

6.5.2 Displaying the Managed System List data in the plug-in 

Now we have a sample plug-in that displays a table of data, we can start 
modifying this code to display our managed system list. 

Because we are going to use the OEMGAMON_SOAP plug-in to provide our 
data, we need to specify a dependency on this plug-in. To do this, from the 
ManagedSystemList Overview panel, select the Dependencies tab at the bottom 
of the panel. 


Note: Double-click pi ugin.xml in the center of the window if you cannot see 
this panel 


On the Dependencies tab, add OMEGAMON_SOAP to the list of required 
plug-ins, and save. This ensures that we can access any exported code from that 
plug-in. 

We next update the ViewContentProvider to display our data rather than the 
sample data. We add a tableData private instance field to hold the data to be 
displayed, a setter method for this field, and we update the getEl ements () 
method to return this field rather than the sample data. The updated version of 
the ViewContentProvider is shown in Example 6-8 on page 186. 
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Example 6-8 Updated ViewConentProvider 

class ViewContentProvider implements IStructuredContentProvider { 
// the data to be displayed in the table 
private String[][] tableData = new String [0] [0] ; 

public void setTabl eData(Stri ng[] [] tableData) { 
this. tableData = tableData; 

} 

public Object [] getEl ements (Object parent) { 
return tableData; 

} 

public void inputChanged(Viewer v. Object oldlnput. Object 
newlnput) { 

} 

public void dispose() { 

} 


We need a new instance field in the ManagedSystemListView to hold a reference 
to the Soaplnterface object that provides our data, and instance fields that 
contains the connection details so add the following lines after the existing field 
declarations in the managedSystemListView class.: 

// the source of our managed system list data 
private Soaplnterface soaplnterface; 

// connection details for the SOAP interface 

private String hostname = "winmvs2c.hursley.ibm.com"; 

private int port = 47587; 

private String userid = "sysadmin"; 

private String password = 

You have to change the host name, port, user ID, and password to match those 
for your system. These values are those used in 6.3.1 , “Connecting to the TEMS 
SOAP interface with the Web client” on page 164. 

At the end of the ManagedSystemListView constructor, add a call to a new 
requestData() method. This method requests the ManagedSystemList and 
update the table with the returned data. 

The implementation of the requestDataQ method is shown in Example 6-9 on 
page 187. 
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Example 6-9 requestDataQ method 


private void requestDataQ { 

if (soaplnterface == null) { 

soaplnterface = new SoapInterface(hostname, port, 
userid, password); 

} 

SoapXMLParser parser = 

soaplnterface. getParsedData(SoapInterface.MANAGED_SYSTEM_LIST_REQUEST) ; 
if (parser != null) { 

String[][] dataTable = parser. getDataTabl e() ; 

( (Vi ewContentProvi der) 

vi ewer. getContentProvi der () ) .setTableData (dataTable) ; 
viewer. refresh () ; 

} 


else { 

showMessage("No data returned - Check host & port"); 



This method creates an instance of the Soaplnterface class if it has not already 
been created, and requests data from this instance. If data is returned, it is 
passed to the ViewContentProvider to be displayed in the table. If no data is 
returned, this is reported in a message. 

If we run the code with these changes, we see a separate but not useful version 
of the managed system list, as displayed in Figure 6-14. 


£ Events l E3 Properties $ ManagedSystemList View tl 

i i ^ ° □’ 

[3 [L java . lang . String ; @1239780 i 

± 

[a] [Ljava . lang . String; @ 12c55e4 
13 [Ljava.Iang.String; @135f0a 

- 

3 [Ljava.Iang.String; @150<Mdd 
3 [Ljava . lang . String; @ 15b2043 
3 [Ljava . lang . String; @ 164b2c0 
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Figure 6-14 Managed System List without columns 


Each row in this panel is a reference to an entry in the managed system list table, 
but we have not yet added the code to extract each row’s data and display it in 
columns. We now add that code. 
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We need to change the presentation of the table so that the column headers are 
displayed and the lines that mark the cells in the table are visible. Do this in 
createPartControl (...) method. After the viewer. setlnput(getViewSiteO) ; 
method, add the information in Example 6-10. 

Example 6-10 Changing the table presentation 

Table table = viewer. getTableQ ; 
table.setHeaderVisible(true) ; 
table.setLinesVisible(true) ; 


We need to update the ViewLabelProvider (which handles the presentation of the 
data in the table) to display each row of data as multiple columns, rather than the 
single reference that we saw previously. This is achieved by replacing the existing 
getCol umnText(...) method with the information in Example 6-1 1 . 

Example 6-1 1 Updating the ViewLabelProvider 

public String getCol umnText (Object obj, int index) { 
if (obj != null) { 

String [] row = (String []) obj; 
return row[index]; 

} 

else { 

return nul 1 ; 


} 


This method simply returns the appropriate cell data from the passed row 
according to the passed column number. Although we are looking at the 
ViewLabelProvider, we can stop icons being displayed in the cells by changing 
the getCol umnlmage(...) method to return null. 

Finally, we need define the new columns in the table, and specify the text for the 
column headers. We define a new method in the ManagedSystemListView class, 
which creates these column definitions as in Example 6-12. 

Example 6- 12 Defining new columns 

private void defineTableColumns (Table table, SoapXMLParser parser) { 

String[] col umnHeaders = parser. getCol umnNames() ; 
for (int i = 0; i < col umnHeaders. 1 ength ; i ++) { 

TableColumn column = new TableColumn (table, SWT. CENTER); 
col umn . setText (col umnHeaders [i ] ) ; 
column. setWidth(lOO) ; 


} 
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This method can only be called when we have data returned from the SOAP 
interface, as our columns and their names are specified in the returned data. We 
invoke this method in the requestData() method. Add the information in 
Example 6-13 before the viewer. refresh() method. 

Example 6-13 Adding before the viewer.refresh() method 

// if we have not previously defined the columns that make up the table 
do it now 

Table table = viewer. getTable() ; 
if (table. getCol umnCount() == 0) { 

defineTableColumns (table, parser) ; 


With these changes in place, we can run the code again. We see a table with 
multiple columns and with headers on each of the columns. It resembles 
Figure 6-15. 



Figure 6-15 Managed System List view with columns 


In this view, we can see the names of all the managed systems in our 
OMEGAMON XE monitoring environment, and we also see any other IBM Tivoli 
Monitoring systems visible to our TEMS. One column of particular interest is the 
Status column, which tells us whether the systems are online or offline. 

Now that we have a list of the systems being monitored, we have several options 
for what we can do next with the plug-in. These include: 

► Moving the requests for data to a more suitable thread 

► Refreshing the data in the table either on demand, or at regular intervals 

► Sorting the data in the table 

► Filtering the data displayed in the table by specific values. 
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We discuss sorting of the data in the table and refreshing the data at a regular 
interval in 6.5.3, “Sorting the Managed System List” on page 190, and leave the 
filtering item and the refreshing of the data when prompted by the user as an 
exercise for the user. A useful side effect of the code that are added to fetch the 
data at regular intervals is that the requests for data is moved to a more suitable 
thread. 

6.5.3 Sorting the Managed System List 

The column to be sorted can be selected by clicking the column header, so we 
need to add code to detect the user clicking the column header. We start by 
defining a Listener class as in Example 6-14. Add this code as an inner class in 
the ManagedSystemListView class. This simple code detects column header 
selection events. When a selection event is detected, it sets the selected column 
and drives a re-sort of the data in the table. 

Example 6-14 ColumnHeaderSelectionListener class 

// the selection listener for the column headers 
class ColumnHeaderSelectionListener implements Listener { 
private final ManagedSystemListView owner; 

ColumnHeaderSelectionListener (ManagedSystemListView owner) { 
this. owner = owner; 

} 


public void handleEvent(Event e) { 

TableColumn currentCol umn = (TableColumn)e. widget; 
Table table = currentCol umn. getParent() ; 

int col Index = -1; 

for (int i = 0; i<tabl e.getCol umnCount() ;i++) { 
if (table. getColumn(i) == currentCol umn) { 
col Index = i ; 

} 

} 

owner. setSortCol umn (col Index) ; 
table. setRedraw (false); 
owner. sort () ; 
table. setRedraw(true) ; 
viewer. refresh () ; 

} 
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Adding the ColumnHeaderSelectionListener class introduces a couple of errors, 
as we need to add further code to the class. To remove the errors, add the 
missing methods and fields to the ManagedSystemListView class. This code is 
shown in Example 6-15. 


Example 6-15 ‘Sort’ fields and methods for ManagedSystemListView class 
// support for column sorting 
private int sortColumn = 0; 
private boolean sortUp = false; 


void setSortCol umn(int 
if (sortColumn 
sortUp 


column) { 

== column) { 
= IsortUp; 


this. sortColumn = colui 


void sort() { 

viewer. getSorter() .sort(viewer, ((IStructuredContentProvider) 
viewer. getContentProviderQ) .getEl ements (nul 1)) ; 

} 


We also need to associate the selection listener with the table columns, so we 
modify the defi neTabl eCol umns (...) method to look like that shown in 
Example 6-16. The only change is to add the line in bold that registers the 
listener with each of the columns as they are created. 

Example 6- 1 6 Updated define TableColumns(. . .) method 

private void defineTableColumns(Table table, SoapXMLParser parser) { 
String[] col umnHeaders = parser. getCol umnNames () ; 
for (int i = 0; i < columnHeaders.length;i++) { 

TableColumn column = new TableColumn (table, 

SWT. CENTER); 

col umn.setText(col umnHeaders [i] ) ; 
col umn.setWidth(lOO) ; 

col umn . addLi stener (SWT .Selection, new 
Col umnHeaderSel ecti onLi stener (this) ) ; 

} 

} 
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Finally, we need to add code to the ColumnSorter class that was created for us 
when the plug-in was created by the wizard. Replace the (currently empty) 
existing implementation of the NameSorter inner class with the version shown in 
Example 6-17. This class provides an implementation of a ViewerSorter class 
that is invoked by the TableViewer’s underlying code when its sort() method is 
invoked. 

Example 6- 1 7 Updated NameSorter class 

class NameSorter extends ViewerSorter { 

private final ManagedSystemListView owner; 

public NameSorter(ManagedSystemListView owner) { 
this. owner = owner; 

} 

public int compare (Vi ewer viewer. Object el. Object e2) { 

// find the two values to be compared (depends on the 
current sort column) 

String valuel = ( (Stri ng [] ) el) [sortCol umn] ; 

String value2 = ((StringG) e2) [sortCol umn] ; 

// guard against null values 
if (valuel == null || value2 == null) { 
return 0; 

} 

if (owner. sortUp) { 

return val uel .compareTo(val ue2) ; 

} 

else { 


return val ue2.compareTo(val uel) ; 

} 



The final change is in the createPartControl(...) class. Replace 
vi ewer. setSorter (new NameSorterO) with viewer. setSorter (new 
NameSorter(this)); 

We now have a plug-in that displays the managed system list and can sort the 
displayed data by the values in any of the columns. This can be useful to group 
systems by their product code, or to group all the offline systems at the top of the 
view. 
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6.5.4 Requesting the Managed System List repeatedly 


The plug-in currently requests the managed system list once when it is created. 
We have two concerns with this: 

► We are doing network I/O on the Display thread. The GUI does not respond 
while the I/O operation is in process. 

► The list is not updated and so does not reflect changes to system status. 

We can address both of these problems by driving the request for data regularly 
on another thread. The changes are simple. 

First, we update the createPartControl (...) method. Remove the last line 
‘requestData();’ and replace it with the code shown in Example 6-18. 

Example 6- 1 8 requestThread 

Thread requestThread = new Thread () { 
public void run() { 

while (true) { 

// request the situations 
requestData() ; 

// and sleep for a bit before fetching the 

situations again 

try { 

Thread. sleep(60000) ; 

} 

catch (InterruptedException e) { 

// woken early - ignore 

} 

} 


requestThread. start () ; 


This code creates a thread that issues and processes the request and then waits 
for one minute (60,000 milliseconds) before repeating, and then starts the thread. 

If we run the plug-in now, we see an org.eclipse.swt.SWTException, as we are 
trying to update the table (an SWT widget) on a thread other than the Display 
thread (the thread that we created previously). We need to change the 
requestData() method to make the updates on the Display thread. The updated 
version of the requestDataQ method is shown in Example 6-19 on page 194. 
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Example 6-19 Updated requestData() method 

private void requestDataQ { 

if (soaplnterface == null) { 

soaplnterface = new SoapInterface(hostname, port, 
userid, password); 

} 

final SoapXMLParser parser = 

soaplnterface. getParsedData(SoapInterface.MANAGED_SYSTEM_LIST_REQUEST) ; 
if (parser != null) { 

Display display = viewer. getTableO .getDisplayO ; 
display.asyncExec(new Runnable () { 
public void run() { 

String [] [] dataTable = 

parser. getDataTable() ; 


// update the table model with the 


passed data 


((ViewContentProvider) 
vi ewer. getContentProvi der () ) .setTableData (dataTable) ; 


the columns 


parser) ; 


// if we have not previously defined 
that make up the table, do it now 

Table table = viewer. getTableO ; 
if (table.getColumnCount() == 0) { 
defineTableCol umns (table. 


}); 


} 


viewer. refresh() ; 


else { 

showMessage("No data returned - Check host & port"); 

} 


The changes (all additions) are highlighted in bold. The reference to the 
SoapXMLParser has been flagged as final so it can be access by the Display 
thread. The code that updates the table is now invoked in an anonymous inner 
class that is invoked on the Display thread. 

We can now run the plug-in knowing that the managed system list updates every 
minute. 
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6.6 Displaying OMEGAMON situations 

Now that we have a plug-in that requests the managed system list from the 
TEMS SOAP interface and displays the list, it is easy to create another plug-in 
that requests and displays Tivoli monitoring situations. These situations are 
user-defined alerts that can be defined to trigger if certain criteria evaluate to 
true. These criteria are typically undesirable performance values (such as CPU 
usage too high, short or storage or transactions blocked waiting for resources) or 
necessary resources becoming unavailable (connection not open or file 
unavailable). Tivoli situations are defined through the TEP interface and can be 
viewed there, but we can also retrieve a list of situations from the SOAP interface. 

First, we need to define the new request that is used to request the situations. 
Add the following instance variable to the Soaplnterface class: 
public static final String SITUATIONS_REQUEST = 

"<tabl e>04SRV . IS ITSTSH</ tabl e><sql >SELECT SITNAME, NODE, ATOMIZE, 
GBLTMSTMP, LCLTMSTMP, ORIGINNODE, PATHNAME, TYPE, DELTASTAT FROM 
04SRV. ISITSTSH WHERE DELTASTAT = 1 Y ' </sql>"; 

This SOAP request uses native SQL to request the data from the TEMS. As you 
can see, the SOAP requests can be constructed from tags that describe the table 
from which the data is extracted, what data is required, and any filters that are 
used to restrict the returned data. In this case, we use SQL to specify this 
information. 

The request syntax is consistent with SQL statements issued against database 
engines and so requires little explanation. The Select statement specifies that we 
want data returned and the columns that are required, the From clause specifies 
the table that is searched for the data, and the Where clause specifies the 
constraints that is applied when choosing which rows from the table are returned. 

Creating a plug-in that displays current situations requires little more than 
copying the plug-in we created to display the managed system list and changing 
the request that is issued to the SOAP interface. Obviously this approach creates 
a significant amount of duplicate code in the two plug-ins and it is a good idea to 
factor out much of this code into common code that is shared by the plug-ins, but 
we do not discuss that here. 

To create the new view, create a new plug-in project, called “SituationView” with 
the new plug-in wizard, following the steps described in 6.5.1, “Creating the 
Managed System List plug-in” on page 182. This time, select the same options in 
the wizard, but with different names on the final panel. See Figure 6-16 on 
page 196. 
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Figure 6- 1 6 Create Situation View - wizard last panel 

We are going to use the OEMGAMON_SOAP plug-in to provide our data so we 
need to specify a dependency on this plug-in. We select the Dependencies tab, 
this time in the pi ugi n.xml file in the SituationsView project that we have just 
created. On the Dependencies tab, add OMEGAMON_SOAP to the list of 
required plug-ins (and save) to allow us to access the code exported from that 
plug-in. 

Next, replace the generated code in the SituationView class with the code from 
the class ManagedSystemListView, but with a few modifications to fetch 
OMEGAMON Situation data rather than the ManagedSystemList. 
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The steps to make these changes are as follows: 

1 . Delete all the code after the package statement in class SituationView, and 
copy the entire contents of ManagedSystemListView (other than the package 
statement in its place. 

2. Replace all instances of ‘ManagedSystemListView’ with ‘SituationView’. 

3. In the requestData() method, change the following line: 
final SoapXMLParser parser = 

soapInterface.getParsedData(SoapInterface.MANAGED_SYSTEM_LIST_REQUEST) ; 
Replace the preceding code with the following line 
final SoapXMLParser parser = 

soapInterface.getParsedData(SoapInterface.SITUATIONS_REQUEST) ; 

Save. 

Run the program and we now have a new view that we can select from the 
Window ->• Show View ->• Other menu option as shown in: Figure 6-17. 



Figure 6-17 Show view - Situation view 
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Selecting this view displays the current situations (if any) in the monitored 
systems, as shown in Figure 6-18. 
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Figure 6-18 OMEGAMON Situations View 


6.7 Displaying OMEGAMON data for specific CICS 
regions 


This chapter has focused on displaying data that applies across the Tivoli 
monitoring systems. We now look at requesting data for specific CICS regions. 
There are a large number of reports supplied as part of the OMEGAMON for 
CICS product, with more being added with new releases to reflect new features 
in CICS. Most of these reports can be driven through the SOAP interface using a 
similar request to that used previously to request the managed system list or 
situations. 


6.7.1 Constructing SOAP queries for CICS data 

Before we code our next plug-in, now is a good time to look at the SOAP request 
format a little more closely. The general form of the SOAP request we are going 
to use to request data about specific CICS regions is as follows: 

<CT_Get> 

<useri d>sysadmi n</useri d><password></password> 

<ob j ect>report_name</ob j ect> 

<target>regi on_ori gi nnode</target> 

<af i 1 ter>col umn_name ; operator ; val ue</af i 1 ter> 

</CT_Get> 

The first and last lines mark the start and end of the request. Again, we are using 
a CT_GET request to request data. 

The second line is also familiar. It contains our user ID and password. 
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The ‘object’ tag (third line) specifies which of the many available reports we are 
interested in. We discuss how you can find a list of these reports in the text that 
follows. 

The ‘target’ tag (fourth line) contains the ORIGINNODE of the CICS region we 
are interested in. This value we can get from the managed system list. 

The ‘afilter’ tag (fifth line) contains the constraints that are used when the data is 
requested. There can be more than one of these tags, each specifying additional 
constraints. These are analogous to the WHERE clause in an SQL SELECT 
statement. The column_name field is the name of the column to which the filter 
applies. The value field is the value that is compared with the column value when 
the server chooses the data to be returned. The operator field is the operator that 
is used in the comparison. Valid operator field values are the usual comparator 
values: 

► EQ (equals), 

► NE (not-equal), 

► GT (greater than) 

► LT (less than) 

► GE (greater than or equal to) 

► LE (less than or equal to) 

Example 6-20 is a sample request for the CICSplex Region Overview report for 
CICS region ZT01.CICSDM25. 

Example 6-20 Sample request 
<CT_Get> 

<useri d>sysadmi n</useri d><password></password> 

<object>CICSplex_Region_Overview</object> 

<target>ZT01.CICSDM25</target> 

<afi 1 ter>0ri gi n_Node; EQ; ZT01 . CICSDM25</af i 1 ter> 

</CT_Get> 


It can be useful to experiment with values in the SOAP request fields either in the 
plug-in code that we create in the section that follows, or using the supplied Web 
client as described in 6.3.1 , “Connecting to the TEMS SOAP interface with the 
Web client” on page 164. 
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Finding values to use in the XML requests 

Because there is a large number of reports that can be driven to request data 
from OMEGAMON CICS, it can be a problem finding out what reports are 
available and what their names are. There are several approaches to this, but 
one approach is as follows: 

1 . View the TEP client and choose a query that contains the data that you are 
interested in. 

2. Right-click the report of interest, and select Properties in the menu. 

3. In the Properties dialog box, click the Click here to assign query button. 

4. Read the query name from the list on the right of the query editor dialog box, 
as shown in Figure 6-19. In this list, the query has spaces between the words 
that make up the name, but we require underscore characters instead of 
spaces. 



Figure 6-19 TEP Query View 

5. Open the DOCKCP file in your TEPS install directory (typically on windows 
this is in c:\ibm\itm\cnps. 

6. Find the query name in the DOCKCP file. It should be on a line that starts 
‘OBJECT: 

7. Scroll down from here to read the column names. These are on lines that start 
with the tag *ATTR: 

When you reach a block of text that includes another ‘OBJECT: tag, you have 
reached the definitions for another report. 


200 


Extend the CICS Explorer: A Better Way to Manage Your CICS 


This gives you the appropriate values to use in the object and afilter tags of the 
SOAP request. 

Alternatively, the report names can be derived from the kcp.atr and kcp.cat 
files. Although these files are more difficult to read, they can be scanned easily 
with a simple program to list all the available reports. This alternative approach is 
described, along with an excellent overview of the SOAP interface, in a technote 
that can be found at the following Web page: 

http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/TD104290 


6.7.2 Displaying the OMEGAMON CICS Region Overview report 

Requesting and displaying the CICS region overview report from OMEGAMON 
requires a similar approach to display the managed system list and the 
situations, but now we must construct the request with the name of the CICS 
system in which we are interested. This requires additional input, as we cannot 
specify the region when we write the code. We are going to allow the user to 
specify the CICS region in two ways: 

► By selecting a monitored CICS region in the managed system list 

► By selecting a CICS region in the CICS Explorer navigation tree. 

Before we implement either of these selection methods, we need to write the 
plug-in that displays the region overview information. 


Tip: Although this example demonstrates requesting the CICS region 
overview, it is a simple matter to change the code to request a different report, 
or to request one of several reports depending on user input or other context. 
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We create the Region Overview in the same way that we created the Situation 
View plug-in; by copying the Managed System List plug-in code and making 
changes as required. Again, we create a plug-in project using the wizard that has 
a Table view. We call the plug-in project RegionOverview and specify the values 
on the wizard’s final panel, as shown in Figure 6-20. 



Figure 6-20 Create Situation View - wizard last panel 

We add OMEGAMON_SOAP to the list of required plug-ins to allow us to access 
the code exported from that plug-in. 

As with the situationView, delete the entire contents of the RegionOverviewView 
class, with the exception of the package statement at the top. Replace this with 
the ManagedSystemListView class, and replace all instances of 
ManagedSystemListView with RegionOverviewView. 

Now we can address the code that requests the region overview for a specific 
CICS region. As we are constructing the SOAP request at runtime, we need an 
instance field to hold the identifier of the CICS region that we are going to 
request data for. The code in Example 6-21 on page 203 contains the field with 
its getters and setters. Add this to the RegionOverviewView class. 
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Example 6-21 origin Node field 


private String originNode; 
public String getOriginNodeQ { 
return originNode; 

} 

public void setOriginNode(String originNode) { 
this. originNode = originNode; 

} 


Next, replace the hard-coded SOAP request in the requestDataQ method with 
the code to construct the request based on the current value of the ‘originNode’ 
field. Replace the following line in the requestData() method with the code in 
Example 6-22: 

final SoapXMLParser parser = 

soapInterface.getParsedData(SoapInterface.MANAGED_SYSTEM_LIST_REQUEST) ; 
Example 6-22 Construct cics region overview request 
if (originNode == null) { 
return; 

} 

String request = "<object>CICSplex_Region_Overview</object>" + 
"<target>" + originNode + "</target>" + 

"<afilter>Origin_Node;EQ;" + originNode + "</afi 1 ter>" ; 
final SoapXMLParser parser = soapInterface.getParsedData(request) ; 


This code checks to see if the originNode value has been set and returns if it hs 
not, because we cannot issue a request without it. It then constructs the request, 
inserting the originNode value as required and then issues the request as before. 

Next we need a way to trigger the issuing of the request. We can achieve this by 
waking the thread that issues the request in the inner class in the 
createPartControl (...) method. We have to gain access to this thread, so we 
change the requestThread local variable in the createPartControl (...) method 
into an instance field in the RegionOverviewView class: 

1 . Add an instance variable ‘private Thread requestThread; to the 
RegionOverviewView class. 

2. Change the line Thread requestThread = new ThreadQ { in the 
createPartControl (...) method, to requestThread = new ThreadQ {. 
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3. Replace the setOrigi nNode(...) method with the code shown in Example 6-23, 
which wakes the request thread when we receive new value for originNode. 


Example 6-23 Updated setOriginNode(. . .) method 
public void setOriginNode(String originNode) { 
this. originNode = originNode; 
requestThread . i nterrupt () ; 

} 


We now need code to drive this view. We make this view display the CICS region 
overview report for the selected CICS region in the managed system list, and 
then we add code to react to selection events in the CICS Explorer. 

We need to tell the Managed System View to make its selection events visible to 
other plug-ins, so add the following lines to the end of the createPartControl (...) 
method of the ManagedSystemListView class: 

// ensure that this table issues selection events that can be detected 
by other plug-ins 

getSite() .setSelectionProvider(viewer) ; 

In its current form, the managed system list table only detects selection events in 
the first column. Although this is sufficient, it is not ideal, so we need to change it 
to detect selections anywhere in the row. We can do this by changing the first line 
of the createPartControl method in the ManagedSystemList class. We need to 
add the SWT.FULL_SELECTION flag in the call to the TableViewer constructor, 
so that the first line becomes: 

viewer = new TableViewer(parent, SWT. MULTI | SWT.H_SCROLL | 

SWT. V_SCR0LL | SWT. FULLSELECTION) ; 

Now that the Managed System List is issuing selection events, we can add code 
to the Region Overview view to listen for them. This code is a new method that is 
shown in Example 6-24. 

Example 6-24 init(..) method 

public void init(IViewSite site) throws PartlnitException { 
super. init(site) ; 

// register ourselves as interested in selection events in 
other views 

site.getPage() .addSelectionListener(new ISelectionListenerQ { 
public void selectionChanged(IWorkbenchPart argO, 
ISelection selection) { 

if (Selection. isEmptyQ) { 

Object firstElement = 
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(Stri ng [] ) fi rstEl ement; 


insufficient columns 


selectedRow[l] ; 
selectedRow[6] ; 


( (StructuredSelecti on) selection) . get Fi rstEl ement () ; 

if (fi rstEl ement instanceof String[]) 
String [] selectedRow = 


false || originNode == null || 

originNode.indexOf(' . ') < 1) 


if (selectedRow. length < 7) { 
// not an MSL row - 

return; 

} 

String originNode = 

String productCode = 
if ("CP" .equal s (productCode) == 


region in the Managed System List 

} 

} 

} 

}); 

} 


// not a CICS region 
return; 


// this is probably a CICS 
setOriginNode(origi nNode) ; 


As this method overrides a method in the super class, it starts with a call to the 
super class’s implementation. The code then creates an inner class that listens 
for selection events from plug-ins within Eclipse. As these selection events might 
come from many plug-ins other than the events we are looking for, the code has 
to check for and reject unexpected values. Most of the code is checking for 
unexpected values, and if one is found, the code returns without further 
processing. 

If the selection event has a String[] as its data component, and if the string array 
is long enough to have come from the Managed System List view, the code 
attempts to read the product code and origin node values from the row. Only if 
the product code matches that for CICS (CP) and if the origin node is of the 
correct format does the code invoke the setOrigi nNode (...) method to drive a 
request for the region overview for the selected CICS region. 
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Tip: Because the Managed System List view uses a simple array of string 
arrays to contain its data, the selection listener for events from it requires 
detailed knowledge of the order of the columns in the table. If this ordering 
were to change, the code fails. A better approach is to use a dedicated class 
to encapsulate the row’s values and provide suitable getter methods to return 
the required values from the row. This approach has not been followed here as 
it increases the complexity of this example, but it is not be advisable to use this 
simple approach in production code. 


We can now run the application to try out our new plug-in. We need to display the 
new view. Navigate to Window ->• Show View ->• Other, as shown in 
Figure 6-21. 



Figure 6-21 Show view: Region Overview view 
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Selecting this view displays an empty table, as we have not yet selected a row in 
the managed system list. However, if we select a CICS region in the managed 
system list, we see the region overview report for that CICS region, as shown in 
Figure 6-22. 



Figure 6-22 Region Overview view 


6.8 Driving an OMEGAMON plug-in from CICS Explorer 

The Region Overview view reacts to selection events in the managed system list. 
Although this can be useful, it is useful to make this plug-in also react to selection 
events in the CICS Explorer. 


Note: For the code that follows to work, your CICS regions must be both 
monitored by OMEGAMON and accessible by the CICS Explorer, either 
through the CMCI interface or CPSM. 


To make the Region Overview plug-in react to selections in the CICS Explorer, 
we need two extensions to the code we have so far: 

► The Region Overview plug-in must detect (and understand) CICS Explorer 
selection events 

► We need to translate between the way that the CICS Explorer identifies a 
CICS Region, and the way that OMEGAMON identifies a CICS Region. 

We deal with these the translation problems first, and then move on to the 
selection events. 
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6.8.1 Translating between CICS Explorer and OMEGAMON identifiers 


OMEGAMON identifies CICS regions by their ORIGINNODE. This is a 
concatenation of the z/OS System ID (SMFID) and CICS region name separated 
by a period character (.). 

The CICS Explorer identifies the CICS region by the value in the NAME field of 
the EYUPARM in the CICS region's JCL. This is typically the CICS region’s 
APPLID, but it might not be. 

Although we are discussing this conversion in the context of the region overview 
report, it can be used in other plug-ins, so it is useful to place the conversion 
routine in a common location that can be accessed easily by multiple plug-ins. 
The OMEGAMON_SOAP plug-in that we created earlier in this chapter is already 
accessed by several plug-ins, so that is a suitable place for this lookup code to be 
implemented. 

When a CICS Explorer event is received by the Region Overview plug-in, the 
plug-in queries the CICS Explorer API to discover the CICS region’s jobname, 
and then it queries the managed system list to find the ORIGINNODE value of 
that CICS region. We can ease the process of looking up the ORIGINNODE 
value by extracting the CICS jobname from the ORIGINNODE value when the 
managed system list is retrieved from the host and maintaining a lookup table 
that maps CICS jobnames to their ORIGINNODE values. The best time to do this 
is when we process a request for the managed system list, and the ideal place to 
do it is in the OMEGAMON_SOAP plug-in. 

We need to make several changes to support a lookup of ORIGINNODE values 
from a CICS jobname. All of these changes are applied to the Soaplnterface The 
first of these changes is simply to add a static field to a Java Map that contains 
the following data: 

private static Map<String, String> jobnameMap; 

Next, add code to the getParsedData() method that invokes the creation (or 
update) of the map if a managed system list has been requested and returned. 
The updated method is shown in Example 6-25 on page 209. 
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Example 6-25 Updated getParsedData(. . .) method 


public SoapXMLParser getParsedData(String request) { 

String xml Result = getData(request) ; 
if (xmlResult != null) { 
try { 

SoapXMLParser parser = new 
SoapXMLParser (xml Result) ; 

// if we were asked for a managed system list, 

create a map 

// of cics jobnames to their ORIGI NNODE values 
if 

(request. equal s(MANAGED_SYSTEM_LIST_REQUEST)) { 

createJobnameMap (parser) ; 

} 

return parser; 

} 

catch (Exception e) { 

e.printStackTrace() ; 
return nul 1 ; 

} 

} 

else { 


return nul 1 ; 



Finally, we need the createJobnameMap(...) method, which populates the map, 
and the getOriginNode(...) method, which returns an ORIGINNODE value for a 
passed jobname if found. These methods are shown in Example 6-26. 

Example 6-26 New Soaplnterface methods 

public static String getOriginNode(String jobname) { 
if (jobnameMap == null) { 
return nul 1 ; 


el se 
} 


return jobnameMap. get(jobname) ; 


private void createJobnameMap (SoapXMLParser parser) { 
// ensure we have an empty map to fill 
if (jobnameMap == null) { 


Chapter 6. Combining OMEGAMON data with CICS Explorer 209 



jobnameMap = new HashMap<String, String>(); 


} 

else { 

jobnameMap. clear() ; 

} 

String[][] table = parser. getDataTable() ; 
if (table != null) { 

for (String [] row : table) { 
if (row. length > 6) { 

String originnode = row[3]; 

String productCode = row[6] ; 
if ("CP".equals(productCode) && 

originnode != null) { 

int separatorlndex = 

originnode.indexOf (" . ") ; 

String jobname = null; 
if (separatorlndex > 0 && 
separatorlndex < originnode. length()-l) { 
jobname = 

originnode. substring (separator I ndex+1) ; 


originnode) ; 


if (jobname != null) { 

jobnameMap. put (jobname. 


} 


} 


Tip: Once again, we have code that requires detailed knowledge of the 
managed system list report. Again, this code would be better if we had a 
dedicated class that encapsulated the report data and provided suitable getter 
methods 
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6.8.2 Detecting and understanding CICS Explorer selection events 


Our first issue is finding out what events are fired when a selection is made in a 
CICS Explorer view. We already have most of the code we require to find out 
about these events. The SelectionListener for the OMEGAMON Region 
Overview report captures selection events published in Eclipse, including those 
from the CICS Explorer. We can see the class of the selection events by adding a 
line to the selection listener immediately after we have assigned the firstElement 
variable, such as: 

System. out. println("Selection, class: " + firstElement. getClassQ + " 
toString " + firstElement); 

We can now run the code, connect our CICS Explorer to a server, and select 
items in the CICS Explorer to view their classes in standard output. 

The first of these selection events was caused by clicking a CICS region in the 
CICS Explorer topology view, the second by clicking a row in the CICS Explorer 
Regions view. Figure 6-23 shows these items selected in the CICS Explorer. 


^acsplex Explorer “ □ 

0 Regions £3 % Tasks 00 Connections] 0 Terr 

Server: JT3A g 

CNX0211I Context: IYK2ZGV1. Resource: CICSRGN. 1 recc 

B 0 JTPLEX2 (3/3) 


Job Name 

^ IYK2ZGV 1 (IYK2ZGV 1) 



! % IYK2ZGV2 (IYK2ZGV2) 
% IYK2ZGV4(IYK2ZGV4) 






Figure 6-23 CICS Explorer CICS region selected 


An example of the output for these selection events is shown in Example 6-27, 
where we have the output for the two events 

Example 6-27 Selection events shown in standard output 

Selection, class: class com. ibm.cics. core. model .internal .ManagedRegion 
toStri ng : ManagedRegi on [I YK2ZGV1] 

Selection, class: class com. ibm.cics. core. model .internal .Region 
toString: com. ibm.cics. core. model .internal .Region[IYK2ZGVl] 


We can see from these two events that we have received instances of two 
separate classes: 

► com. ibm.cics. core.model. internal. ManagedRegion 

► com. ibm.cics. core.model. internal. Region 
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We cannot add either of these classes to the dependencies for our plug-ins, as 
they are not made available to us by the SDK plug-ins, but we can go looking for 
Interfaces that they implement. For many of the internal CICS Explorer classes, 
there is a publicly visible interface that has the same name as the class, but with 
a letter T as a prefix. When we look for these interfaces (Navigate to Menu -> 
Open type) we see that these interfaces are both defined in the 
com. ibm.cics. model (as shown in Figure 6-24) package, which we can access 
from our plug-ins. 


Tip: This technique can be applied to detecting and identifying any selection 
events from the CICS Explorer. 
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Now that we know what events we are expecting from the CICS Explorer, our 
next challenge is extracting the information we require from these events that we 
have received. If we look at the methods in these interfaces we see that the 
IRegion Interface has a getJobname() method that returns a string. This is what 
we need to find the CICS region in our managed system list, with a little work. 
The IManagedRegion Interface does not have such a useful method and 
presents us with additional challenges, so for now we focus on getting the 
IRegion selection event working and come back to the IManagedRegion event 
later. 

We can react to the IRegion event from the CICS Explorer with a simple piece of 
code, but we need to give the Region Overview plug-in access to the 
com..ibm.cics.model package so that we can cast the received event into the 
appropriate type. Select plugin. xml in the RegionOverview and go to the 
Dependencies tab. Here we add the package to the Imported Packages list as 
shown in Figure 6-25. 



Figure 6-25 Region Overview add dependencies 

Next, add another clause to the IF statement in our selection listener in 
RegionOverviewView, as shown in Example 6-28. 

Example 6-28 IRegion clause in selection listener 

if (Iselection.isEmptyO) { 

Object firstElement = 

((StructuredSelect ion) selection) . get First El ement(); 
if (firstElement instanceof String []) { 


} 

else if (firstElement instanceof IRegion) { 

IRegion region =(IRegion) firstElement; 
String jobname = region. getJobName() ; 
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// try to find an ORIGINNODE for this jobname 
String originNode = 

Soaplnterf ace. getOriginNode( jobname) ; 

if (originNode != null) { 

setOriginNode(originNode) ; 


} 


This additional code extracts the jobname from the received event and uses the 
code we wrote to look up the ORIGINNODE of CICS region. Given the 
ORIGINNODE, we can drive the Region Overview report in the same way as 
when a CICS region was selected in the managed system list. 

As the I Region event is fired when a row is selected in the Regions table view in 
the CICS Explorer, we can now test this code. We get results like those shown in 
Figure 6-26. 



Figure 6-26 CICS Explorer Regions and OMEGAMON 

We can now move on to the challenge of handling events from the navigation 
tree, the IManagedRegion events. The IManagedRegion does not have a 
reference to a jobname, so we have to go through several other steps. 

To get the jobname, we have to get an instance of an IRegion object for ourselves 
by driving the CICS Explorer’s API. The IManagedRegion object has a reference 
to the name that CICS Explorer uses to identify the CICS region. This is the main 
thing that we need when we want to get an IRegion instance. Because we expect 
to use this several plug-ins, we place this code in the OMEGAMON_SOAP 
plug-in. The code we use is based on the code introduced in 5.1 .3, “Using our 
sample code” on page 98, but with a few differences. For simplicity, we have 
placed all this code in static methods in a new class called ExplorerWrapper in 
the OMEGAMON_SOAP plug-in. This new class is shown in Example 6-29 on 
page 215. We have included the import statements for clarity. 
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Example 6-29 ExplorerW rapper. java 
package omegamon_soap; 


import com. ibm.cics. core. model .CICSTypes; 
import com. ibm.cics. core. model .ICPSM; 
import com. ibm.cics. core. model . IResourcesModel ; 
import com. ibm.cics. core. model .ScopedContext; 
import com. ibm.cics. core. ui .UlPlugin; 
import com. ibm.cics. model .ICICSplex; 
import com. ibm.cics. model . IManagedRegion; 
import com. ibm.cics. model .IRegion; 

public class ExplorerWrapper { 

public static String getJobName( IManagedRegion managedRegion) { 
ICPSM cpsm = (ICPSM) 

UIP1 ugin.getDefaul t() .getResourceManager( 

UIP1 ugin.SYSTEM_MANAGER_CONNECTION_ID) ; 
if (cpsm != null) { 

// we need to find the context for the passed managed region 
String context = getContext(cpsm, managedRegion); 
if (context != null) { 

ScopedContext scopedContext = 

new ScopedContext(context, managedRegion. getNameO) ; 
IResourcesModel regionModel = 

cpsm.getModel (CICSTypes. Region, scopedContext) ; 
if (regionModel != null) { 
regionModel .activate(); 
regionModel .maybeFetch(0,-l) ; 
if (regionModel .size() > 0) { 

regionModel .maybeFetch(0, regionModel .size()) ; 
IRegion region = (IRegion) regionModel .get (0) ; 
String jobname = region. getJobName() ; 
return jobname; 

} 

} 

} 

} 

// failed to find the jobname 
return nul 1 ; 

} 

private static String getContext(ICPSM cpsm, IManagedRegion 
managedRegion) { 

// find the pi ex containing the passed managed region 
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ICICSpl ex [] plexes = cpsm.getCICSplexes() ; 
if (plexes != null) { 

if (plexes. length == 1) { 

// only one plex - must be the right one 
return pi exes [0] .getName() ; 

} 

else { 

// test each plex in turn 

String searchRegionName = managedRegion.getName() ; 
for (ICICSplex plex : plexes) { 

IManagedRegion[] regions = cpsm.getManagedRegions(plex) ; 
for (IManagedRegion region : regions) { 

if (region. getName() .equals(searchRegionName)) { 

// found the owning cmas 
return pi ex.getName() ; 

} 



// we have failed to find the owning cmas 


return nul 1 ; 
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When you create the ExplorerWrapper class as shown in Example 6-29 on 
page 215, you have multiple compile errors due to the plug-in not having 
dependencies on the necessary CICS Explorer plug-ins. By a process of 
searching for the classes referenced in the errors using the technique described 
in 4.3.3, “Adding CICS Explorer code to the Eclipse Template code” on page 82, 
we found that the required dependencies that have to be added to 
OMEGAMON_SOAP are as shown in Figure 6-27. 



Figure 6-27 OMEGAMON_SOAP Explorer dependencies 


The code in Example 6-29 on page 215 deserves discussion. The only public 
method is the getJobName(...) method. It is passed an IManagedRegion instance, 
and it returns the jobname for that CICS region. It starts by getting a connection 
to the host through the CICS Explorer API (the cpsm reference). After we have 
this reference, we need to find the context for the passed IManagedRegion. This 
is achieved by the getContext method, which queries every CICS region name 
on every plex until it finds a matching region name. It can then return the owning 
CMAS. 


Note: The ManagedRegion object actually has a reference to its context, but 
this is not currently available through the IManagedRegion interface. As the 
CICS Explorer SDK is still evolving, this reference might become available in 
the future, which removes the need for the getContext (...) method. 


After we have the context, we can query the IManagedRegion for its name, which 
is the scope for the query we are about to issue. Given the context and scope, we 
can now request the CICSTypes. Region (IRegion) that we require. When we 
receive this object we cast it into an IRegion and extract the jobname that we 
return. 

This code can be easily modified to retrieve a jobname based on other objects 
received from the CICS Explorer. 
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The final piece of code is another clause in the if statement in our selection 
listener in RegionOverviewView, as shown in Example 6-30. 

Example 6-30 IManagedRegion clause in selection listener 

if(!selection.isEmpty()) { 

Object firstElement = 

( (StructuredSel ecti on) sel ecti on) .get Fi rstEl ement () ; 
if (firstElement instanceof String []) { 


} 

else if (firstElement instanceof IRegion) { 


} 

el se 


if (firstElement instanceof IManagedRegion) { 

IManagedRegion managedRegion = (IManagedRegion) firstElement; 
String jobname = ExplorerWrapper.getJobName(managedRegion) ; 
String originNode = SoapInterface.getOriginNode(jobname) ; 
if (originNode != null) { 

setOriginNode(originNode) ; 

} 


This code drives the getJobName(...) method we described and then drives the 
OMEGAMON code to fetch the region overview for the selected CICS region. 

If we run the code now, we can see the OMEGAMON Region Overview for any 
CICS region selected in the tree, without having to select that CICS region in the 
CICS Explorer Regions view, as shown in Figure 6-28. 
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Figure 6-28 CICS Explorer tree selection and OMEGAMON 
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We now have a plug-in that displays OMEGAMON data related to the currently 
selected CICS region in CICS Explorer. It is a simple matter to modify this code 
to display other OMEGAMON reports based on other selections in the CICS 
Explorer. 


Summary 

In this chapter we have discussed the SOAP interface into the Tivoli Enterprise 
Management Server (TEMS) that allows access to a variety of OMEGAMON 
data. We have used this interface to provide information for several plug-ins that 
are useful in their own right, but that also provide examples from which to create 
your own reports displaying other OMEGAMON data. 

We have also demonstrated how to drive OMEGAMON reports based on 
selections in the CICS Explorer. This code can be used as a basis for other 
reports that you might want to create. 

The code and techniques described here can also be used when writing other 
extensions to the CICS Explorer for data sources other than OMEGAMON. 
Additionally, these examples can be used to integrate OMEGAMON data with 
products other than CICS Explorer. 

Other possible extensions to the plug-ins created here include other 
representations of the data, such as graphs or a hierarchical view of the 
managed system list that is similar to the to the physical navigation tree view in 
the Tivoli Enterprise Portal (TEP) client. That requires interesting code to convert 
the data into a tree structure, but after this had been done, it provides a useful 
plug-in from which to navigate through the available data that can be retrieved 
from the SOAP interface. 
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6.10 References and further reading 

The information and code presented in this chapter gives you a good starting 
point when writing your own Eclipse plug-ins that integrate OMEGAMON data 
and features with the CICS Explorer. The following is a list of several other 
sources of information that might prove useful. 

6.10.1 IBM Tivoli Monitoring Information Center 

This is the definitive guide to the components that make up the ITM architecture, 
and includes extensive details about the configuration and usage of the TEMS 
Web services interface. This includes a discussion of the other commands 
available in the SOAP interface that have not been discussed in this chapter. 

6.10.2 OMEGAMON XE for CICS Information Center 

This provides detailed information about the features available in OMEGAMON 
XE for CICS, and provides detailed information about the available reports that 
you can exploit in your plug-ins. 

6.10.3 IBM Open Process Automation Library (OPAL) 

This site brings together a selection of documents, best practices and tools for 

products across the range of Tivoli software: 

http : //www-01 . i bm.com/software/brandcatal og/portal /opal / 

6.10.4 IBM Tivoli Monitoring Eclipse plug-in 

This plug-in makes use of many of the concepts demonstrated in this chapter 
and provides access to data from CICS and CICS Transaction Gateway: 
http: //www-01 . i bm.com/software/brandcatal og/portal /opal /detai 1 s?catal og 
.label=lTW100MlD 

6.10.5 Using IBM Tivoli Monitoring V6.1 SOAP Services 

This document provides an excellent overview of the TEMS Web services 
interface and its usage: 

http: //www-01 . i bm.com/software/brandcatal og/portal /opal /detai 1 s?catal og 
.label =1TW10TM4M 


220 Extend the CICS Explorer: A Better Way to Manage Your CICS 


7 


Setting CICS Trace Levels 
through CICS Explorer 


CICS tracing is a great tool for understanding how and why a system or 
application is experiencing a problem. It traces the flow of execution through 
CICS code and through user applications. You can see what functions are being 
performed, which parameters are being passed, and the values of important data 
fields at the time trace calls are made. 

At defined trace points, CICS writes variable length tracing entries into the CICS 
trace table. Trace points are used to make trace entries when exception 
conditions occur. These trace points are always captured. Other trace points are 
used to trace the mainline execution of CICS code. These trace points are each 
associated with a level attribute. CICS allows you to control how much CICS 
system tracing is to be done based on the trace level setting for each trace 
component. 

This chapter describes the necessary steps to create an CICS Explorer plug-in 
that allows you to set CICS trace levels dynamically for each trace component, 
similar to the functionality provided by the CICS CETR transaction. 
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7.1 The Trace Component Plug-in 


In this example you create an Eclipse JFace viewer to display the CICS trace 
components and accept the users input of which components to turn on or off 
and what levels to set. It is important to understand three main concepts of 
viewers when dealing with JFace viewers: 

► Viewer: The user interface (for example, the tableviewer in this example) 

► Content provider: Provides the model objects to the viewer 

► Label provider: Defines how the model objects are displayed 

This project consists of three main components: 

► A model that represents the data for the plug-in 

► A view that displays the data 

► A pop-up display that allows the view to be displayed 

Begin by creating a blank plug-in and add the necessary extension points, 
packages, classes, and methods as you go along. This plug-in requires two 
images that must be located in the icons folder for the project. After you create 
your project, make sure you have the following two images in the icons folder: 

► checked.gif 

► unchecked.gif 

You can find the images for these two icons in the additional materials for this 
IBM Redbooks publication. 


7.2 Creating the project 

Start off by creating a project to contain all the classes for your plug-in. Switch to 
the Plug-in Development perspective and select File ->• New ->• Project ->• 
Plug-in project and click Next. The first page of the wizard displays. Enter the 
project name as cics. set. trace and click Next. 

On the second page of the wizard, set the default properties. Click Next. 


Note: You are going to create a blank plug-in without using a template. 
However, if you want to create this plug-in using a template as in prior 
examples, in the third page of the wizard, select Custom plug-in wizard and 
click Next. Then, in the Template Selection page select Popup Menu and 
View and click Next. You need to add appropriate names for the view and 
pop-up menu settings. See 7.4.1, “Adding extension points and packages” on 
page 227 for naming conventions for this example. 
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In the third page of the wizard, clear the Create a plug-in using one of the 
templates check box and click Finish. Your plug-in project has now been 
created along with the default manifest files and the activator class. Because you 
did not use a template, the view class was not generated. You create this class in 
a later step. 

An activator class controls the lifecycle of a plug-in as well as any images used in 
the plug-in that are managed by the ImageRegistry. If the project has a class that 
extends AbstractUIPIugin (for example, Activator.java), there must be a 
getimageDescriptor ( ) method to access ImageDescriptors given a path to 
the image. In this example, you are using two check box images, so you must 
add this method to the Activator.java class. 


Note: If you used a template to create this plug-in, the getlmageDescri ptor() 
method was generated automatically when the activator class was created. 


Open the Activator.java class in the “set.cics.trace” package and add the code in 
Example 7-1. 

Example 7-1 getimageDescriptor method 

public static ImageDescriptor getimageDescriptor (String path) { 
return imageDescriptorFromPlugin (PLUGIN_ID , path); 

} 


You get an error because the ImageDescriptor class must be imported. Add the 
following import 

import org. eel ipse. j face. resource. ImageDescriptor; 

Save and close the activator class. Next, you create the model structure for your 
project. 


7.3 Creating the model 

This project uses two simple classes that represents the data model in your 

design. The Component class is a simple object representing a trace component 

with getters and setters for the following properties: 

private String compld; 

private String stdTraceLevel ; 

private String spcTraceLevel ; 

private boolean selected; 
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The ComponentModel class is used to hold a collection of Component instances. 
So, let’s create the model. 

Within your project, create the package cics.set.trace. model (right-click the 
project, select New Package). Create the Component class (Example 7-2) in 
this package. 

Example 7-2 Component class 
package cics . set . trace .model ; 
import java .beans .* ; 

public class Component { 
private String compld; 
private String stdTraceLevel; 
private String spcTraceLevel; 
private boolean selected; 

private PropertyChangeSupport propertyChangeSupport = 
new PropertyChangeSupport (this) ; 

public Component () { } 

public Component (boolean selected, String compld, 

String stdTraceLevel, String spcTraceLevel) { 
super () ; 

this . selected = selected; 

this. compld = compld; 

this . stdTraceLevel = stdTraceLevel; 

this . spcTraceLevel = spcTraceLevel; 

} 


} 


public void addPropertyChangeListener ( 

String propertyName , PropertyChangeListener listener) { 
propertyChangeSupport 

.addPropertyChangeListener (propertyName, listener) ; 


public void removePropertyChangeListener ( 
PropertyChangeListener listener) { 
propertyChangeSupport 

. removePropertyChangeListener (listener) ; 


} 


public String getCompId() { return compld; } 
public String getSpcTraceLevel ( ) { return spcTraceLevel; } 
public String getStdTraceLevel ( ) { return stdTraceLevel; } 
public boolean isSelected() { return selected; } 
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public void setCompId (String compld) { 
this.compld = compld ; 

} 

public void setSpcTraceLevel (String spcTraceLevel) { 

propertyChangeSuppor t . f irePropertyChange ( " spcTraceLevel " , 
this . spcTraceLevel , 

this . spcTraceLevel = spcTraceLevel); 

} 

public void setStdTraceLevel (String stdTraceLevel) { 

propertyChangeSupport . f irePropertyChange ( "stdTraceLevel" , 
this . stdTraceLevel , 

this . stdTraceLevel = stdTraceLevel); 

} 

public void setSelected (Boolean isSelected) { 

propertyChangeSupport . f irePropertyChange ( " selected" , 
this . selected, this . selected = isSelected); 

} 

public String toStringO { 

String text = compld + "1="; 

if (stdTraceLevel. equals ("1") ) text += "1"; 
else if (stdTraceLevel .equals ("1-2") ) text += "2"; 
else if (stdTraceLevel .equals ("OFF") ) text += "0"; 
else text += stdTraceLevel; 

text += + compld + "2="; 

if (spcTraceLevel. equals ("1-2") ) text += "2"; 
else if (spcTraceLevel .equals ("OFF") ) text += "0"; 
else text += spcTraceLevel; 

return text; 

} 


As you review this class, notice there is one additional parameter specified, 
properChangeSupport. This parameter is used to add a PropertyChangeListener 
to each property. A Property Change Event occurs when a property value has 
changed. In this plug-in you have three properties that can change: 

► selected 

► stdTraceLevel 

► spcTraceLevel 

You add a PropertyChangeListener to the setter methods for each property to 
listen for any changes. 


Chapter 7. Setting CICS Trace Levels through CICS Explorer 225 


Next, create the ComponentModel class in this same package (Example 7-3). This 
module initializes each of the trace components levels for both standard and 
special and provides a collection of all the trace components. It sets all standard 
tracing to level 1 and all special tracing to level 1-2, unless that component only 
has level 1 tracing. 

Example 7-3 ComponentModel class 
package cics . set . trace .model ; 
import j ava . util . * ; 

public class ComponentModel { 

private static ComponentModel content; 
private List<Component> components; 

// there are 65 trace components total 
public String [] compld = { 

"AP" , "BA" , "BM" , "BR" , "CP" , "DC" , "DD" , "DH" , "DM" , "DP" , 

"DS" , "DU" , "El" , "EJ" , "EM" , "EP" , "FC" , "GC" , "IC" , "IE" , 

"II" , "IS" , "KC" , "KE" , "LC" , "LD" , "LG" , "LM" , "ME" , "ML" , 

"MN" , "NQ" , "OT" , "PA" , "PC" , "PG" , "PI" , "PT" , "RA" , "RI" , 

"RL" , "RM" , "RS" , "RX" , "RZ" , "SC" , "SH" , "SJ" , "SM" , "SO" , 

"ST" , "SZ" , "TC" , "TD" , "TI" , "TR" , "TS" , "UE" , "US" , "WB" , 

"WU" , "W2" , "XM" , "XS" } ; 

// these components only have Level 1 tracing 

private String[] spcLIOnly = { 

"BM" , "DC" , "KC" , "PC" , "SC" , "SZ" , "TD" , "UE" } ; 


public ComponentModel ( ) { 

components = new ArrayList<Component> () ; 

// initialize each entry 

for (int i=0; i<compId . length ; i++) { 

Component component = new Component () ; 
component. setSelec ted (false) ; 
component. setCompId (compld [i] ) ; 
component . setStdTraceLevel ( " 1 " ) ; 

if (Arrays . asList{ spcLIOnly) . contains (compld [i] ) ) 
component . setSpcTraceLevel ( " 1 " ) ; 
else 

component . setSpcTraceLevel ("1-2") ; 
components . add (component) ; 

} 

} 

public static synchronized ComponentModel getlnstance () { 
if (content != null) 
return content; 
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content = new ComponentModel ( ) ; 
return content; 


} 

public List<Component> getComponents ( ) { 
return components; 

} 


7.4 Creating the view 

Now that you have the data model structure complete, you can create the view. 
Because you are working with a blank plug-in, you need to add the extension 
points and import any packages required for this plug-in. 


Note: If you used a template in the earlier step, some of these extension 
points might already be added to your plug-in project. 


7.4.1 Adding extension points and packages 

First, add the extension points. In the manifests files, click the Extensions tab and 
click Add under All Extensions. On the “Extension Point Selection” page, select 
org.eclipse.ui.views under “Extension Points” and select Sample View under 
“Available templates”. Click Next. On the next page, specify the following values: 

► View Class Name: TraceComponentView 

► View Name: Trace Component View 

► View Category Name: CICS Category 

You are using a table viewer for this view, so ensure it is selected. Click Finish to 
add this extension point and create the plug-in class. Notice that three extensions 
have been added to the Extensions tab for your plug-in. 

You just added the view template to your project. Because this plug-in uses a 
pop-up menu as well, you need to add one more extension for the pop-up menu 
extension point. Click Add again and select org.eclipse.ui.popupMenus under 
“Extension Points” and select Popup Menu under “Available templates” and click 
Next. On the next page add this pop-up menu to the Regions resource, so 
specify the following values 

► Target Object’s Class: com. ibm.cics. model. IRegion 

► Submenu Name: CICS Trace 

► Action Label: Set Components 
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► Action Class: SetComponents 

Click Finish. You might get a pop-up window asking to save the changes made 
to the plug-in. Click Yes. Notice that following extensions have been added to the 
Extensions tab for the plug-in: 

► org. eel ipse. ui .views 

► org. eel ipse. ui .perspecti veExtensions 

► org. eclipse. help. contexts 

► org. eel ipse. ui .popupMenus 

Next, add the CICS packages this plug-in requires. Because it is activated when 
a CICS region is selected, you are using the Region resource. Add that package 
and a few others. In the manifests files, click the Dependencies tab and click Add 
under “Required Plug-ins”. Add the following packages for the plug-in: 

► com. ibm.cics. core. comm 

► com. ibm.cics. core. model 

► com. ibm.cics. core. ui 


Note: If you do not know what packages are required, you can add them at a 
later time. 


You are now ready to code the view and pop-up classes. 

7.4.2 Modifying the pop-up action class 

This view is opened when you right-click a CICS region and select CICS 
Trace -» Set Components. You now add the code to make that happen. Open 
the pop-up class, SetComponents.java, in the cics.set.trace.pop-up.actions 
package. In this class you need to declare a global variable, region, and alter the 
selectionChanged() and run() methods. Modify this class to look like 
Example 7-4. 

Example 7-4 SetComponents class 
package cics . set . trace . popup . actions ; 

import org . eclipse . j face . action . IAction ; 
import org . eclipse . j face . viewers . * ; 
import org . eclipse . swt . widgets . Shell ; 
import org. eclipse. ui. *; 

import com . ibm . cics . model . IRegion ; 

public class SetComponents implements IObjectActionDelegate { 
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SSuppressWarnings ( "unused" ) 
private Shell shell; 

0SuppressWarnings ( "unused" ) 
private IRegion region; 

public SetTrace() { 
super () ; 

} 

public void setActivePart (IAction action, 
IWorkbenchPart targetPart) { 
shell = targetPart. getSite () .getShell () ; 

} 


} 


public void run (IAction action) { 
final IWorkbenchPage page = 

Platf ormUI . getWorkbench ( ) . getActiveWorkbenchWindow ( ) 

. getActivePage () ; 

try { 

@SuppressWarnings ( "unused" ) 

IViewPart view = page 

. showView ( " cics . set . trace . views . TraceComponentView" ) ; 
} catch (PartlnitException e) { 
e .printStackTrace () ; 


} 

public void selectionChanged ( IAction action, 
ISelection selection) { 

region = (IRegion) ( (StructuredSelection) selection) 
.getFirstElement() ; 


} 


Test your pop-up menu. Run the plug-in as an Eclipse application and connect to 
a WUI region. Right click a region in the Region view. See Figure 7-1 . 
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If you select Set Components, the view looks like Figure 7-2. 



Figure 7-2 Trace Component View: Default 


This shows that the pop-up is working as it opens the view. You might notice 
there is not much to this view, as this is the default view. 

7.4.3 Modifying the view class 

It is time to add the code for how the view looks. Expand the cics.set.trace.views 
package and open the TraceComponentView.java class. There are several 
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default methods that were generated in this class. You modify a few of these 
classes and add a few more to create your view, but there are some you do not 
use. All other methods except for those in the following list might be deleted, as 
they are not used by this plug-in: 

► NameSorter() 

► makeActions() 

► contributeToActionBars() 

► fillLocalToolBarO 

► setFocus() 

► showMessage() 

You also need to alter the contributeToActionBars() method and remove the 
reference to fill Local Pul 1 Down(). Also alter the createPartcontrol () method 
and remove hookContextMenu() and hookDoubleCl ickAction(). 

Begin coding. First, import your data model. 

import java.io.*; 

import java.net.*; 

import java. util .List; 

import cics. set. trace. model .*; 

import com. ibm. cics. model .*; 

import com. ibm. cics. core. model .*; 

import com. ibm. cics. core. ui .*; 

This class is defined with four variables already. You are using them all but you 
rename a few. Define the following global variables for your view: 

private Table table; 
private ICPSM cpsm; 
private I Reg ion region; 
private Context context; 
private int portNum; 
private String host; 

List<Component> componentList = 

ComponentModel .getlnstancef) .getComponentsQ ; 

Then, perform the following steps: 

1 . Rename all references to actionl to selectAl 1 . 

2. Rename all references to action2 to deselectAl 1 . 

3. Rename all references to doubled ickActi on to submit. 

These parameters are used as you build the necessary methods. If you have all 
the dependencies and imported packages set up correctly, you do not receive 
any errors. Now, create the table by adding the following method, createTableQ, 
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to the class. This method creates a table of four columns to hold your data. See 
Example 7-5. 

Example 7-5 createTable method 


public void createTable (Composite parent) { 

String [ ] titles = { "Component", "Standard", "Special" }; 

int [ ] bounds = { 20, 100, 100, 100 }; 

table = viewer . getTable ( ) ; 
table . setHeaderVisible (true) ; 
table . setLinesVisible (true) ; 

for (int i = 0; i < titles . length ; i++) { 

TableViewerColumn column = 

new TableViewerColumn (viewer , SWT . NONE) ; 
column . getColumn ( ) . setText ( titles [ i ] ) ; 
column . getColumn ( ) . setWidth (bounds [i] ) ; 
column . getColumn ( ) . setResizable (true) ; 


You need to add a call to the createTable () method in the createPartControl () 
method for the table to be set up. The modified version of this class looks like 
Example 7-6. 

Example 7-6 Modified createPartcontrol method 

public void createPartcontrol (Composite parent) { 

System. out. println ("In createPartcontrol. . .") ; 
viewer = 

new TableViewer (parent, SWT. MULTI | SWT.V_SCROLL 
| SWT . FULL_SELECTION) ; 

createTable (parent) ; 

viewer . setContentProvider (new ViewContentProvider ( ) ) ; 
viewer . setLabelProvider (new ViewLabelProvider () ) ; 
viewer. setSorter (new NameSorter ()); 
viewer . setlnput (getViewSite () ) ; 

/ / Create the help context id for the viewer ' s control 
Platf ormUI . getWorkbench ( ) . getHelpSystem ( ) 

. setHelp (viewer .getControl () , "cics . set . trace .viewer") ; 
makeActions ( ) ; 
contributeToActionBars () ; 
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If you run the example, the view contains a table with four columns, as shown in 
Figure 7-3. 



Figure 7-3 Trace Component View: Table with four columns 


Next, alter the ContentProvider to indicate what data objects to use and the 
LabelProvider to define how the data is displayed. Instead of creating your own 
classes, alter the ViewContentProvider() and ViewLabel Provider () methods. 
You need to import the Activator, so add the following import statement: 
import cics. set. trace. Activator; 

The updated ViewContentProvider and ViewLabelProvider are shown in 
Example 7-7. 


Example 7-7 Modified ViewContentProvider and ViewLabelProvider methods 


class ViewContentProvider implements IStructuredContentProvider { 
@SuppressWarnings ( "unchecked" ) 

public Object[] getElements (Object inputElement) { 

List<Component> components = (List<Component>) inputElement ; 
return components . toArray ( ) ; 

} 

public void dispose () { 

} 

public void inputChanged (Viewer viewer, Object oldlnput, 

Object newlnput) { 

} 


} 


class ViewLabelProvider extends LabelProvider 
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implements ITableLabelProvider { 
private final Image CHECKED = Activator .getlmageDescriptor ( 
"icons/checked. gif ") . createlmage ( ) ; 
private final Image UNCHECKED = Activator .getlmageDescriptor ( 

" icons/unchecked. gif ") . createlmage () ; 

public Image getColumnlmage (Object element, int columnlndex) { 
//In case you don't like image just return null here 
if (columnlndex == 0) { 

if (((Component) element) . isSelected () ) { 
return CHECKED; 

} else { 

return UNCHECKED; 

} 

} 

return null ; 

} 

public String getColumnText (Object element, int columnlndex) { 
Component component = (Component) element; 
switch (columnlndex) { 

case 0: return String. valueOf (component. isSelected() ) ; 

case 1: return component. getCompId() ; 

case 2: return component. getStdTraceLevel () ; 

case 3 : return component . getSpcTraceLevel ( ) ; 

default: throw new Run timeException ("Should not happen"); 

} 

} 

} 


Before you can test the plug-in, verify the two icon files are in the icons folder for 
your project. You must alter the createPartControl() method to set the input. In 
createPartControl() change the statement viewer. setlnput(getViewSiteO) to 
viewer. setlnput(componentList) ; 
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Run the plug-in as an Eclipse application. In the new Eclipse window that opens, 
connect to the host and right-click a region in the Regions tab as shown in 
Figure 7-4. 
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Select CICS Trace -> Set Components. The view shown in Figure 7-5 displays. 



At this point, you can scroll up and down but none of the fields are yet editable. 
Add this part next so that you can select which components to set and what level 
to which to set them. Use the JFace CellEditor class to specify how the user can 
edit each cell in the table. Each column contains the following items: 

► Column 1 : A selectable check box 

► Column 2: An uneditable text field 

► Column 3 and 4: Drop-down list boxes displaying possible options to set. 

Create a new class, TraceEditor, which extends the EditingSupport class in the 
cics. set. trace. model s package to define what each column is and what data it 
displays. Create the class shown in Example 7-8. 

Example 7-8 TraceEditor class 
package cics . set . trace .model ; 
import j ava. util. Array s; 

import org . eclipse . j face . viewers . * ; 
import org. eclipse. swt. SWT ; 
import org . eclipse . swt . widgets . * ; 

public class TraceEditor extends EditingSupport { 
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private CellEditor editor; 

private Composite parent; 
private int column ; 

// arrays for the various levels of tracing 
private String[] levell= { "OFF", "1" }; 
private String[] level2 = { "OFF", "1", "1-2" }; 
private String[] level3 = { "OFF", "1", "1-2", "3" }; 

// arrays for components with level 1 tracing only 
private String [] llOnly = { 

"BM" , "DC" , "KC" , "PC" , "SC" , "SZ" , "TD" , "UE" } ; 

// arrays for components with level 1 and 2 tracing only 
private String [] 120nly = { 

"AP" , "BR" , "CP" , "EC" , "El" , "FC" , "IC" , "RA" , 

"RI" , "SJ" , "TC" , "WB" , "WU" } ; 

public TraceEditor (ColumnViewer viewer, int column) { 
super (viewer) ; 

parent = ( (TableViewer) viewer) .getTable() ; 
this. column = column; 


protected boolean canEdit (Object element) { 
return true ; 

} 

protected CellEditor getCellEdi tor (Object element) { 
Component c = (Component) element; 

// create the correct editor based on the column index 
switch (this. column) { 
case 0: 

editor = new CheckboxCellEdi tor (null , SWT . CHECK \ 

SWT . READ_ ONL Y) ; 

editor = new TextCellEdi tor (parent, SWT . READ_ONLY) ; 
case 2 : 

if (Arrays . asList (llOnly) . contains (c . getCompId ()) ) 
editor = new ComboBoxCellEdi tor (parent, levell); 
else if (Arrays . asList (120nly) . contains (c . getCompId ( ) ) ) 
editor = new ComboBoxCellEdi tor (parent, level2) ; 
else 

editor = new ComboBoxCellEdi tor (parent, level3) ; 
break ; 

if (Arrays . asList (llOnly) . contains (c . getCompId ()) ) 
editor = new ComboBoxCellEdi tor (parent, levell); 
else if (Arrays . asList (120nly) . contains (c . getCompId () ) ) 
editor = new ComboBoxCellEdi tor (parent, level2) ; 
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else 

editor = new ComboBoxCellEdi tor (parent, level3); 
break; 

default: break; 

} 

return editor; 


protected Object getValue (Object element) { 

Component c = (Component) element; 
switch (this . column) { 
case 0: return c.isSelected() ; 
case 1: return c.getCompId() ; 

case 2 : if (c.getStdTraceLevel () .equals ("OFF") ) 
return 0; 

else if (c.getStdTraceLevel () .equals ("1") ) 
return 1; 

else if (c.getStdTraceLevel () .equals ("1-2") ) 
return 2; 

else if (c.getStdTraceLevel () .equals ("3") ) 

case 3:if (c.getSpcTraceLevel () .equals ("OFF") ) 
return 0 ; 

else if (c.getSpcTraceLevel () .equals ("1") ) 
return 1 ; 

else if (c.getSpcTraceLevel () .equals ("1-2") ) 
return 2; 

else if (c.getSpcTraceLevel () .equals ("3") ) 
return 3; 
default: break; 

} 

return null ; 


protected void setValue (Object element, Object value) { 

Component c = (Component) element; 

switch (this . column) { 

case 0 : c . setSelected ( (Boolean) valued- 
break; 

case 1 : c. setCompId (String. valueOf (value) ) ; 
break; 

case 2 : if (((Integer) value) == 1) { 
c . setStdTraceLevel ( " 1 " ) ; 
c . setSelected (true) ; 

} else if (((Integer) value) == 2) { 
c. setStdTraceLevel ("1-2") ; 
c . setSelected (true) ; 

} else if ( ( (Integer) value) == 3) { 
c . setStdTraceLevel ( " 3" ) ; 
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c.setSelected(true) ; 

} else { 

c . setStdTraceLevel ( "OFF" ) ; 
c.setSelected(true) ; 

} 

break; 

case 3 : if (((Integer) value) == 1) { 
c . setSpcTraceLevel ( " 1 " ) ; 
c.setSelected(true) ; 

} else if (((Integer) value) == 2) { 
c. setSpcTraceLevel ("1-2") ; 
c.setSelected(true) ; 

} else if ( ( (Integer) value) == 3) { 
c . setSpcTraceLevel ( "3" ) ; 
c.setSelected(true) ; 

} else { 

c . setSpcTraceLevel ( "OFF" ) ; 
c.setSelected(true) ; 

} 

default : break ; 

} 

getviewer() .update (element, null) ; 

} 

} 


The main methods within this class do the following: 

► The getCel 1 Editor method returns the celleditor you want to use. This is 
implemented using a switch statement and is based on the column. 

► The setVal ue method receives a new value from the user input and sets the 
new value to the object. 

► The getVal ue method receives the object that was changed and returns the 
value for the table. 

Next, assign the editors to the table columns. This is done in the createTableQ 
method in the TraceComponentView.java class. Modify this method as shown in 
Example 7-9. 

Example 7-9 Modified createTable method 

public void createTable (Composite parent) { 

System. out. println ("In createTable. . . ") ; 

String [ ] titles = { "Component", "Standard", "Special" }; 

int [ ] bounds = { 20, 100, 100, 100 }; 

table = viewer . getTable ( ) ; 
table . setHeaderVisible (true) ; 
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table . setLinesVisible (true) ; 


for (int i = 0; i < titles . length; i++) { 

TableViewerColumn column = new TableViewerColumn (viewer , 
SWT . NONE ) ; 

column. getColumn() . setText (titles [i] ) ; 
column . getColumn () . setWidth (bounds [i] ) ; 
column . getColumn () . setResizable (true) ; 
column . setEditingSupport (new TraceEdi tor (viewer , i) ) ; 

} 

} 


Run the plug-in. You are now able to edit the columns as shown in Figure 7-6. 
The check boxes are now selectable and the fields in the Standard and Special 
columns are now drop-down lists displaying all the available trace settings for 
each given component. 



Figure 7-6 Plug-in with editable fields 


You now have your view the way you want it. The next step is to add functionality 
so that you can submit the changes to the table to the host system, setting the 
actual trace components to the specified level. You start with the three action 
buttons you renamed in an earlier step (that is, selectAII, deselectAII, and 
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submit). Edit the fill Local Tool Bar () method as shown in Example 5-10 to add 
each of these buttons to the local toolbar for your view. 

Example 7-10 Modified fillLocalToolBar methods 

II add the 3 buttons to the local tool bar 
private void fillLocalToolBar (IToolBarManager manager) { 
manager . add (selectAll) ; 
manager . add (deselectAll) ; 
manager . add (submit) ; 


Edit the makeActi ons () method as shown in Example 5-1 1 to specify what each 
button does when it is selected. 

Example 7-11 Modified makeActions method 

II specify the action for each button 
private void makeActions () { 
selectAll = new Action () { 

public void run() { 

for (Component c: componentList) (c . setSelected(true) ; } 
viewer . refresh ( ) ; 

} 

} ; 

selectAll. setText(" Select All") ; 

deselectAll = new Action () { 

public void run() { 

for (Component c: componentList) (c . setSelected (false) ; } 
viewer . refresh ( ) ; 

} 

} ; 

deselectAll . setText ( "Deselect All") ; 

submit = new Action () { 

private String text; 

public void run() { 
text = 

for (Component c : componentList) { 

if (c.isSelected() ) { text += c + } 

} 

// submit request if port available 
if (portNum >0) { 

text = text. substring (0, text . length ( ) - 1); 
setTracing (portNum, text) ; 

} else { 
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showMes sage ("You must first define a TCPIPService" 
+ "number to submit this request."); 

} 

} 

}; 

submit. setText(" Submit") ; 


The selectAII and deSelectAII buttons toggle the check box on and off for all 
components. The main button here is the Submit button, which calls the 
setTracing() method. When this button is clicked, a URL request is built based 
on the selected trace components. For this example to work, a TCPIPService 
definition with a valid port must be available for the selected CICS region (for 
example, HTTPNSSL). Before you take a look at the setTracing() method that 
creates the URL and sends the request to CICS, create an i ni t () method that 
obtains the region name and available port number each time a region is 
selected. Add the method shown in Example 7-12 to the TraceComponentView 
class. 

Example 7- 12 init method 

public void init (IViewSite site) throws PartlnitException { 
super . init (site) ; 

// add selection listener to look for when users click a 
/ / Region entry in the Region view to acquire region name 
site . getPage () . addSelectionListener (new ISelectionListener () { 

public void selectionChanged(IWorkbenchPart argO , 

ISelection selection) { 
if (! selection . isEmpty () ) { 

Object firstElement = 

( (StructuredSelection) selection) . getFirstElement () ; 
if (firstElement instanceof IRegion) { 
region = (IRegion) firstElement ; 
portNum = getTcpipPort (region) ; 


As you can see, this method calls the getTcpipPort () method to obtain the 
available port number. Add the method in Example 7-13 to the class. 

Example 7- 1 3 getTcpipPort method 

public int getTcpipPort (IRegion region) { 
int port = 0; 
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cpsm = UI Plugin . getDe fault ( ) ,getCPSM() ; 

ICICSplex[] cicsplexes = cpsm.getCICSplexes () ; 

//set scopedContext (CPSM, CPSM) 
host = cpsm . getHost ( ) ; 

ScopedContext scopedContext = new ScopedContext 

(cicsplexes [0] .getName() , cicsplexes [0] .getNameO) ; 
plexContext = new Context (scopedCon text. getCon text ()) ; 
ITCPIPService [ ] tcpipServices = null; 

IResourcesModel model = cpsm. getModel (CICSTypes. TCPIPService , 
plexContext) ; 

model . activate () ; // Initiate the model 

if (model . size () >0) { // Check there are objects to get 
tcpipServices = new ITCPIPService [model . size ()] ; 
model .maybeFetch (0 , model . size ()) ; // Fetch the results 
for (int i = 0; i < model . size () ; i++) 

tcpipServices [i] = (ITCPIPService) model . get (i) ; 

} 

for (ITCPIPService tcpipService : tcpipServices) { 
if ("HTTPNSSL" .equals (tcpipService. getName () ) ) { 

if (tcpipService . getRegionName () .equals (region . getName () ) ) 
port = tcpipService. ge tPort () ,intValue() ; 
else { 

port = 0; 

showMes sage ("There is currently no port available " 
+ "in region " + region . getName () 

+ " . You need to define a TCPIPService 
+ "definition for HTTPNSSL") ; 

} } 

} 

return port; 


The getTcpipPort () method does the following: 

► Obtain the host name of the connected CICSPlex SM 

► Obtain the name of the Context for the selected CICSPlex 

► Obtain a list of all TCPIPService definitions within the sysplex 

► Search this list for a TCPIPService named HTTPNSSL 

► Check this HTTPNSSL definition is defined in the selected CICS region 

If yes, get the port number. Otherwise, put out a message that a 
TCPIPService definition is required for the selected region. 

Return the port number and then call the setTracingO method to build the URL 
request and send it to the host system. Next, create the setTracingO method 
(Example 7-14). 
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Example 7-14 setTracing method 


private void setTracing (int port, final String t) { 
HttpURLConnection conn = null ; 

Buf feredReader rd = null; 

StringBuilder sb = null; 

String line = null; 

String url = null; 

URL serverAddress = null; 

try { 

url = "http: //"+host+" : "+port+"/CICS/CWBA/COBSETTR?"+t; 
serverAddress = new URL (url) ; 

//set up out communications stuff 
conn = null ; 

//Set up the initial connection 

conn = (HttpURLConnection) serverAddress . openConnection () ; 

conn . setRequestMethod ( "GET" ) ; 

conn . setDoOutput (true) ; 

conn . setReadTimeout (10000) ; 

conn. connect () ; 

//read the result from the server 
rd = new Buf feredReader (new 

InputStreamReader (conn.getInputStream() ) ) ; 
sb = new StringBuilder () ; 

while ((line = rd . readLine ( ) ) != null) { 

sb. append (line + ' \n'); 

} 

MessageDialog . openln formation ( 

viewer . getControl ( ) . getShell ( ) , 

"Result" , 

sb. toString () ) ; 

} catch (MalformedURLException e) { 
e.printStackTrace () ; 

} catch (ProtocolException e) { 
e.printStackTrace () ; 

} catch (IOException e) { 
e.printStackTrace () ; 

} finally { 

//close the connection, set all objects to null 
conn . disconnect ( ) ; 
rd = null ; 
sb = null ; 
conn = null ; 

} 

} 
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7.5 CICS TS Application 


You have now completed all the coding necessary on the front-end. The last 
piece required is the back-end program that gets called (COBSETTR). This 
program is a CICS Web Support SPI program written in COBOL which performs 
the following tasks: 

► Executes an EXEC CICS INQUIRE TRACETYPE (STANDARDISPECIAL) for 
each component to inquire on the current value 

► Parses the HTML data sent by CICS Explorer to extract each component 
name and level to set for both standard and special tracing 

► Executes an EXEC CICS SETTRACETYPE (STANDARDISPECIAL) for each 
component to set the new value 

► Returns an HTTP response to indicate the success of the request to CICS 
Explorer 

The COBSETTR program is supplied in the additional materials for this book. 

You need to make sure you have a TCPIPService definition called HTTPNSSL 
set with CWBA in the host system. 

After you have the back-end program in place and loaded into the load library, 
execute this plug-in and the following actions occur: 

► When you click the Select All button, all components are selected. 

► When you click the De-select All button, all components are unselected. 

► When you click the Submit button, the URL request is sent to the host system 
kicking off the COBSETTR API program, the trace components are set for the 
selected region, and the message in Figure 7-7 is displayed upon completion. 



Figure 7-7 Message box indicating trace successfully set on host 

Press the Enter key after making your last selection before clicking the Submit 
button in order for all changes to take affect. 
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Note: There are few features that could be added to this plug-in if time 
allowed. They are listed here for future reference: 

► The plug-in does not poll the host system to query what the current 
settings for CICS trace components are. Therefore, it does not recall what 
was set or is set in the region. 

► An option to turn all trace components off by the click of a button. 
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8 


Adding a sticky note plug-in 
to CICS Explorer 


In this chapter we document a plug-in that implements a sticky note memo 
function in your CICS Explorer. You can use this facility to annotate the resources 
in your CICS Explorer workspace, and to view and manage the sticky notes that 
have been created. 

From the point of view of writing plug-ins for CICS Explorer, what is interesting 
about this plug-in is that it demonstrates how you can provide additional input 
data that is useful to you, but which is not related to mainline CICS Explorer 
function. This pluf, and have that data saved and managed by a plug-in beyond 
the standard provide input date and data this wtin 

The plug-in implements a pop-up that can be opened from any CICS Explorer 
resource or definition view. 

In this chapter we describe: 

► A specification for the memo plug-in 

► The code created to implement the plug-in 

► How to use the plug-in 


© Copyright IBM Corp. 2010. All rights reserved. 
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8.1 The specification for your sticky note plug-in 


Start your CICS Explorer, and connect to the target CICS WUI region, then 
left-click the Operations tab in the action bar, and select any of the resources. 
You get a view like that shown in Figure 8-1 , showing all the programs installed in 
the CICSPlex scope within which you are working. 


i^) Regions URI Maps [^] Programs £2 

CNX0211I Context: EPRED 

. Resource: PROGRAM. 9,918 records collected at 05-Nov-2009 1C 

Region Name 

Status 
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Concurrent... 
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0 
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Enable 
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Figure 8- 1 CICS Explorer operations view 


If you right-click one of the programs, CICS Explorer presents you with a pop-up 
menu offering a number of actions that you can perform on that program (for 
example, Disable, Enable, or New Copy). 

This plug-in adds a new action, Add Sticky Notes, to the pop-up menu presented 
when you right-click any CICS Explorer resource, allowing you to associate a 
piece of text with that resource. 

The plug-in allows you to view and manage the sticky notes that have been 
created within your CICS Explorer. 

In this example you create an Eclipse JFace viewer to display the sticky notes 
that have been created, you also create a pop-up to allow users to create new 
sticky notes. 
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We are working with three main concepts: 

► Viewer 

The user interface (the tableviewer in this example) 

► Content provider 

Provides the model objects (sticky notes) to the viewer 

► Label provider 

Defines how the sticky notes are displayed 
This project consists of three main components: 

► A model 

Represents the data for the plug-in 

► A view 
Displays the data 

► A pop-up menu 

Allows the view to be displayed 

We begin by creating a blank plug-in and then add the necessary extension 
points, packages, classes, and methods as we go along. 
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8.2 Overview of components 


The diagram in Figure 8-2 gives an overview of the components created and 
modified to produce this plug-in. The white boxes are the Java packages created 
either by the Eclipse wizards or by you. The colored boxes are the different 
classes either modified or created for this project. 



Figure 8-2 Overview of sticky notes Packages 


The createPartControl (), ViewContentProvider(), ViewLabel ProviderQ and 
Cel 1 Modi fierSample() methods are Eclipse-plug-in extension methods that have 
been modified with custom code for our purposes. The addSnoteObject() 
saveNotes(), and deleteNotesQ methods are methods we added to the 
StickyNotesView package generated by Eclipse for our new view. 

sti ckyNotesVi ews .snoteQ is a new standalone object containing the code which 
manages the internals of the sticky notes object. 

The stickyNotesViews package (which in retrospect we should have named 
stickyNotesViewsActions) contains the actions associated with our sticky notes 
view. You can click actions in the toolbar of the sticky notes views to save or 
delete the sticky notes (StickyNotesViewsSave() and 
Sti ckyNotesVi ewsDel ete()). 
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The stickyNotesViews.pop-up.actions package is generated by Eclipse tooling to 
contain the code associated with the actions you can perform when you 
right-click a CICS object and select sticky notes. You can add a note through the 
pop-up menu (stickyNotesViewAddNotesO). 


8.3 Using a wizard to create your new plug-in 

Start your Eclipse development environment, and select File -» New -^Project. 
Select Plug-in Project, then click Next. The first page of the wizard displays. 
Enter the project name as StickyNotes and click Next. 

In the second page of the wizard, set the default properties. Click Next. 


Note: We are going to create a blank plug-in without using a template. 
However, if you want to create this plug-in using a template as in prior 
examples, on the third page of the wizard, select Custom plug-in wizard and 
click Next. In the Template Selection page, select Popup Menu and View and 
click Next. You need to add appropriate names for the view and popup 
settings. See 5.4.1, “Specification of new textbox and button” on page 125 for 
naming conventions for this example. 


In the third page of the wizard, clear the Create a plug-in using one of the 
templates check box and the Activator class, then click Finish. Your plug-in 
project has been created with the default manifest files and no activator class. 
Because you did not use a template, no view or pop-up class was generated. You 
create this class in a later step. 

You are now ready to create the model structure for our project. 


8.4 Creating the model 

This project uses a single class that represents the data model in our design. The 
SNoteObject class is a simple object representing a sticky note component with 
getters and setters for the following properties: 

private String SnoteName; 
private String SnoteType; 
private String SNoteComment; 
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Within your project, create the package sti ckynotes . snote (right-click the 
project, select New ->• Package). Create the SNoteObject class in this package, 
and copy in the code shown in Example 8-1 . 

Example 8-1 SNoteObject 

package stickyNotesViews . snote ; 

public class SNoteObject{ 

String SNoteName ; 

String SNoteType; 

String SNoteComment; 

public SNoteObject (String snotename, String sno te type , String 
snotecomment) { 

SNoteName = snotename; 

SNoteType = snotetype ; 

SNoteComment = snotecomment ; 

} 

public String getSNoteName (){ return SNoteName;} 
public String getSNoteType () {return SNoteType;} 
public String getSNoteComment () {return SNoteComment; } 

public String setSNoteName (String string) { 

SNoteName = string; 
return null ; } 

public String setSNoteType (String string) { 

SNoteType = string; 
return null ; } 

public String setSNoteComment (String string) { 

SNoteComment = string; 
return null ; } 


} 


8.5 Creating the pop-up 

Now that the data model structure is complete for your sticky notes object, you 
can create the pop-up which is going to allow users to create a sticky note. 
Because you are working with a blank plug-in, you need to add the extension 
points and import any packages required for this plug-in. 


Note: If you used a template in the earlier step, some of these extension 
points might already be added to your plug-in project. 
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8.5.1 Adding extension points and packages for pop-up 


You need to add an extension for the pop-up menu extension point. Open the 
manifest editor for your StickyNotes project by double-clicking the MANIFEST.MF 
object. Click Add and select org. eel ipse. ui .pop-upMenus under Extension 
Points. Select pop-up Menu under Available templates and click Next. 

As you are going to make sticky notes available to be used with any CICS 
resource, you need to associate your new function with the generic CICS 
Explorer object representing a CICS resource or definition. On the next page, 
add this pop-up menu to the ICICSObject resource by specifying the following 
values: 

► Target Object’s Class: com. ibm.cics. model .ICICSObject 

► Submenu Name: sticky notes 

► Action Label: Add Sticky Notes 

► Action Class: StickyNotesViewsAddNotes 

Click Finish. You might get a pop-up window asking to save the changes made 
to the plug-in. Click Yes. When you have saved your new AddSti ckyNotes action, 
click it. See Figure 8-3. 


Extension Element Details 

Set the properties of 'action'. Required fields are denoted by '*'. 

id*: SfickyNotesPopupAction. new Action 

label*: [ Add Sticky Notes 

class*: v i . actions. StickyNotesViewsAddNote^ [Browse... 

definitionld: [Browse... 

menubarPath: MakeNotePopupAction.menul/groupl 

icon: | Browse... 

helpContextld: [_ 

style: | [ft 

state: | \s 

enablesFor: | 1 

override Actionld : | Browse .. . 


Figure 8-3 Add Sticky Notes Extension details 
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Add global variables to the class as shown in Example 8-2. (The imports 
generated by Eclipse have been suppressed in this figure.) 

Example 8-2 . Sticky Notes pop-up globals 
package sticky. notes . popup . actions ; 

import org. eel ipse. j face. acti on. IAct ion; 
import st i cky . notes . snote . SNoteObj ect ; 
import com. ibm.cics. model . ICICSObject; 

public class Sti ckvNotesVi ewsAddNotes implements IObjectActionDelegate 

{ 


private Shell shel 1 ; 

public ICICSObject icicsobject; 

private String notetext; 


You need to update the run() method of the StickyNotesViewsAddNotes_object. 
This is the code invoked when the user clicks this action in the pop-up menu. 
When the user selects Add Sticky Note, the updated run() method 
(Example 8-3) invokes the addSNoteobjectQ method of the sticky notes view to 
update the list object containing the list of sticky notes. 

Example 8-3 run() method of StickyNotesViewsAddNotes 

public void run(IAction action) { 

String dial ogT i t 1 e = 

icicsobject. getCICSType() .getlnterfaceTypeQ .getName() ; 

dial ogT i t 1 e = dialogTitle.substring(dialogTitle.lastIndexOf(".") + 

2 ); 

String dialogMessage = "Resource name : " + icicsobject. getNameQ ; 
String initialValue = "input text notes"; 

InputDialog inputdialog = new InputDialog(shel 1 , dialogTitle, 
dialogMessage, initialValue, 
new IlnputVal idator() { 

^Override 

public String isVal id(String newText) { 
if (newText. length() == 0) { 
return "input text !"; 

} else { 

notetext = newText; 
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return null; 


} 

} 

}); 

if (inputdialog.open() == Dialog. OK) { 

IWorkbench workbench = PI atformlll .getWorkbench() ; 
IWorkbenchWindow window = workbench. getActi veWorkbenchWindow() ; 
IWorkbenchPage page = window. getActi vePageQ ; 

try { 

ViewPart sampleView = (ViewPart) page 
.findView("stickyNotesViews.views.StickyNotesView") ; 

if (sampleView == null) { 

sampleView = (ViewPart) page 

.showView("stickyNotesViews. views. St ickyNotesView") ; 


} 

SNoteObject snoteobject = new SNoteObject( 

icicsobject.getName() , dialogTitle, notetext); 
((StickyNotesView) sampleView) .addSNoteObject(snoteobject, 
sampleView); 

} catch (PartlnitException e) { 
e.printStackTraceQ ; 

} 


} 


At this point, you might have an error flagged in Eclipse because you have not yet 
defined your sticky notes view. 

You also need to modify the SelectionchangedQ method so that when the user 
clicks a CICS resource to add a sticky note, information about that resource is 
saved. See Example 8-4. 

Example 8-4 SelectionChanged() method of tickyNotesViewsAddNotes 

public void selectionChanged(IAction action, ISelection selection) { 
icicsobject = (ICICSObject) ((StructuredSelection) selection) 
.getFirstElement() ; 


Next, you have to write the code to manage the new sticky notes view. 
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8.5.2 Adding extension points and packages for view 


To add the extension points, open the manifest file for your plug-in, click the 
Extensions tab, and perform the following steps 

1 . Click All Extensions -» Add. 

2. In the Extension Point Selection panel, select Extension Points -> 
org.eclipse.ui.views, and Available templates -> Sample View. Click Next. 

3. Specify the following values 

- View Class Name: Sti ckyNotesVi ew 

- View Name: Sticky Notes View 

- View Category Name: sticky Notes 

4. You are using a table viewer for this view so ensure it is selected. Click Finish 
to add this extension point and create the plug-in class. 

Notice that three extensions have been added to the Extensions tab for our 
plug-in: one for the eclipse view plug-in, one for the eclipse perspective extension 
plug-in, and one for the eclipse help context plug-in. You have added the view 
template to your project and Eclipse has created a StickyNotesView.java file for 
you. You are ready to insert the code to implement the sticky notes view. In 
Example 8-5 you can see the global variables that you need to add. 

► Initialize the table columns for the table in our view 

► Create a hashmap i tem to manage your sticky notes objects. 

► Use the Java Memento object to create a sticky note 

Example 8-5 Global variables for StickyNotesView.java 

public class StickvNotesView extends ViewPart { 

/** The ID of the view as specified by the extension. **/ 
public static final String ID = 

"sti cky_notes .views . Sti ckyNotesVi ew" ; 

private static final String[] col umnNames = { "Name", "Type", 
"Comment" }; 

private static final int[] columnWidths = { 100, 120, 300 }; 

private TableViewer viewer; 

private Action actionl; 

private TableColumn column; 

final String DIRECT0RY_PATH = 

ResourcesPlugin.getWorkspace() .getRootQ .getLocation() .toOSString() ; 
final String TEMP_CSVFILE = "sti ckyNotesTemp" ; 
final LinkedHashMap<SNoteObject, ViewPart> items = new 
LinkedHashMap<SNoteObject, 

ViewPart>() ; 


256 


Extend the CICS Explorer: A Better Way to Manage Your CICS 


In Example 8-6 you see the changes you need to make to the 
ViewContentProvider class in the template generated by Eclipse. Change the 
getElements() method of this class to return an array of sticky notes objects from 
the entries in the items hash table. 

Example 8-6 Changed code to return array of sticky notes objects 

class ViewContentProvider implements IStructuredContentProvider { 
public void inputChanged(Viewer v. Object oldlnput. Object 
newlnput) {} 

public void disposeQ {} 

public Object [] getEl ements (Object parent) { 

return items . keyset ( ) . toArray ( ) ; } 

} 


In Example 8-7 you see the changes to the ViewLabelProvider class. It is called 
to populate the table that is being created. Depending on the column that is being 
called to populate, it returns the appropriate sticky note name, type or, text. 

Example 8-7 Changes to ViewLabelProvider 

class ViewLabel Provider extends Label Provider implements 
ITableLabel Provider { 

public String getCol umnText (Object obj, int index) { 

SNoteObject snoteobject = (SNoteObject) obj; 
switch (index) { 

case 0:return snoteobject. getSNoteName() ; 
case l:return snoteobject. getSNoteType() ; 
case 2:return snoteobject. getSNoteComment() ; } 
return null;} 

public Image getCol umnlmage(0bject obj, int index) {return null;} 
public Image getlmage(0bject obj) { 

return PI atformUI.getWorkbench() . getShared Images () .get Image ( 
ISharedlmages . IMG_OBJ_ELEMENT) ; } } 


Modify the CellModifierSample class as shown in Example 8-8, to use the 
SNoteObject. 

Example 8-8 CellModifierSample 

public class CellModifierSample implements ICel 1 Modi tier { 
private TableViewer viewer; 
public CellModifierSample(TableViewer viewer) { 
this. viewer = viewer;} 

OOverride 

public boolean canModify (Object element. String property) { 
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return true;} 

POverride 

public Object getVal ue(0bject element. String propety) { 
SNoteObject snoteobject = (SNoteObject) element; 

Object snote = null; 
if (propety. equal s( "Comment")) { 

snote = snoteobject. getSNoteComment() ;} 
return snote;} 

OOverride 

public void modi fy (Object element. String propety. Object value) 

Tableltem tableltem = (Tableltem) element; 

SNoteObject snoteobject = (SNoteObject) tableltem. getData() ; 
if (propety. equal s( "Comment")) { 

snoteobject . setSNoteComment ( (Stri ng) val ue) ; } 
viewer. update (snoteobject, null);}} 


It is the createPartControl () method, as shown in Example 8-9 that builds the 
view. In our case, it builds a view suited to our sticky notes display. It invokes a 
series of methods to set up the action bars, context help, and so forth. Because 
sticky notes are saved across restarts of Eclipse, this method invokes the 
readfi 1 e () method to retrieve the sticky notes saved the last time Eclipse was 
run. 

Example 8-9 createPartControl Method 

public void createPartControl (Composite parent) { 

viewer = new TableViewer(parent, SWT. MULTI | SWT.H_SCROLL 
| SWT. V_SCR0LL | SWT. FULL_SELECTION) ; 
vi ewer . setContentProvi der (new Vi ewContentProvi der () ) ; 
viewer.setLabel Provider (new ViewLabel ProviderQ) ; 
viewer. setlnput(getViewSiteO) ; 

// Create the help context id for the viewer's control 

PI atformUI .getWorkbench() .getHel pSystem() .setHel p(viewer.getControl () , 
"Sti cky_Notes . vi ewer") ; 
makeActions() ; 
hookContextMenu() ; 
contributeToActionBars() ; 

Table table = viewer. getTable() ; 
table.setHeaderVisible(true); 
table. setLinesVisible(true) ; 

// Set the column headers 
for (int i = 0; i < col umnNames. length; i++) { 
column = new TableColumn(table, SWT. LEFT); 
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col umri. setText (col umnNames [i] ) ; 
col umn.setWidth(col umnWidths[i] ) ;} 

CellEditor[] cell editor = new CellEditor[] { new 
TextCel 1 Editor(tabl e) , 

new TextCel 1 Editor(table) , new TextCel 1 Editor(table) }; 
viewer.setCol umnProperties(col umnNames) ; 
vi ewer . setCel 1 Editors (cel 1 edi tor) ; 

vi ewer. setCel 1 Modi fier(new Cel 1 Modi fierSample(vi ewer)) ; 
readFi 1 e (TEMPCSVFI LE) ; } 


We are going to add an action which allows the user to delete the selected sticky 
note from the list. Example 8-10 shows themakeActions() method that 
implements this action. You can see that it invokes the remove () method of the 
items object to remove the selected object. It then refreshes the view, with the 
object removed. 

Example 8- 1 0 makeActions() method of Sticky Notes View 

private void makeActions() { 
actionl = new ActionQ { 

public void run() { 

final StructuredSelection selection = (StructuredSel ection) 

viewer 

.getSelection() ; 

for (Object obj : selection. toArrayO) 
i terns. remove (obj); 
viewer. refresh () ; 
try {saveNotes (TEMP_CSVFILE) ; 

} catch (UnsupportedEncodingException e) { 
e.printStackTrace();}} 

}; 

actionl. setText("Delete Sticky Note"); 

actionl. setToolTipText(" Remove this Sticky Note"); 

actionl.setImageDescriptor(PlatformUI .getWorkbench() .getSharedlmages () 

. get ImageDescri ptor( IShared Images. IMG_OBJS_INFO_TSK)) ; 

?} 


In Example 8-11 on page 260, we see the addSnoteObject() method that is 
invoked to add a new StickyNote into the table. We then refresh the view. This 
code is invoked by the pop-up action code to add a sticky note to our list, and 
then refreshes the view to pick up the new sticky note. You can see that each 
time a sticky note is added to the list, we save the entire list to a temporary .csv 
file. 
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Example 8- 1 1 addSNoteObjectQ method 

public void addSNoteObject(SNoteObject snoteobject, ViewPart 
sampleView) { 

items. put(snoteobject, sampleView) ; 

viewer. refresh () ; 

try {saveNotes (TEMP_CSVFILE) ; 

} catch (UnsupportedEncodingException e) {}} 


In Example 8-12 we see the deleteNotes() method of our StickyNotes view. 
When invoked, this method deletes all the StickyNotes in the list. 

Example 8-12 deleteNotes() method 

public void del eteNotes () { 
items. clear() ; 
viewer. refresh () ; 
try {saveNotes (TEMPCSVFI LE) ; 

} catch (UnsupportedEncodingException e) {}} 


The code that manages the saving of the sticky notes to a .csv file is in the 
saveNotes() method is shown in Example 8-13. 

Example 8-13 saveNotes() method 

public void saveNotes (String fileName) throws 
UnsupportedEncodingException { 

String filePath = DIRECTORY_PATH + "\\" + fileName + ".csv"; 
try {FileOutputStream fos = new Fi 1 eOutputStream(fi 1 ePath, false); 
OutputStreamWriter osw = new OutputStreamWriter(fos, "UTF-8"); 
BufferedWriter bw = new BufferedWriter(osw) ; 

Table table = viewer. getTable() ; 

for (int i = 0; i < table. getItemCount() ; i++) { 

Tableltem items = table. getltem(i) ; 
bw.write(items.getText(0) + + items. getText(l) + 

+ items. getText(2)) ; 
bw.newLine();} 
bw.flush() ; 
bw.close() ; 
osw.close(); 
fos.close(); 

} catch (FileNotFoundException e) {e.printStackTrace() ; 

} catch (UnsupportedEncodingException e) {e.printStackTraceQ ; 

} catch (IOException e) {e.pri ntStackTrace() ;} } 
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The routine that reads saved sticky notes from the .csv file can be found in 
Example 8-14. The .csv file is created within the Eclipse workspace in the home 
directory of the Eclipse being used, with the name TEMP_CSVFILE . csv. If Eclipse is 
closed down and restarted, the data is retrieved by the createPartControl 
method when the sticky notes view is opened. 

Example 8-14 readFile() method 

public void readFile(String file_name) { 

String filePath = DIRECTORY_PATH + "\\" + TEMP_CSVFILE + ".csv"; 
try {File file = new File(filePath) ; 

BufferedReader br = new BufferedReader(new Fi 1 eReader (fi 1 e) ) ; 
String str; 

while ((str = br.readLineQ) != null) { 

String[] strArray = str.spl it (" , ") ; 

SNoteObject snoteobject = new SNoteObject (strArray [0] , 
strArray [1], strArray [2] ) ; 
items. put(snoteobject, null); 
vi ewer. refresh () ;} 
br.close() ; 

} catch (FileNotFoundException e) { 

} catch (IOException e) {}} 


Although we have added code to the view to handle the saving and deletion of 
our sticky notes, we have not yet added extensions to the view to create the 
actions on the toolbar that you can click to perform the save and the delete. 


8.5.3 Adding extension points and code for Delete View Action 

We need to create the extensions and code that deletes a sticky notes list, or 
save a sticky notes list to a .csv file so that it can be saved across starts of CICS 
Explorer. 

If it is not already open, double-click the MANIFEST.MF object in the package 
explorer, and select the Extensions tab in the view. We are going to add an 
exention to the org.eclipse.ui.vewActions plug-in. Click Add, and then select the 
org.eclipse.ui.vewActions plug-in. Now we can add our new View Actions. 
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Right-click the org.eclipse.ui.vewActions object in the extensions list, and select 
New viewContribution. See Figure 8-4. 



Figure 8-4 Add viewContirbution 

Call the new viewContribution StickyNotes, and give it a target ID of 
StickyNotesView. 

Right-click your new StickyNotesviewContributionl , and select New, then an 
action. Give this action an ID of StickyNotes. actionl. You are prompted for the 
name of the class that is going to execute the new action. Click class to create 
the new class in the stikyNotesView package, and call it 
stickyNotesViews.StickyNotesViewsDelete. (We create this class and add it to 
the sticky NotesViews package shortly). 

Next, we are going to add a graphic to the toolbar, which the user can click to 
delete all the sticky notes. Right-click the StickyNotesviewContributionl again but 
this time select New ->• Menu. Give the new menu a name of 
StickyNotes. menul. In the path box, enter additions, and in the icon box, add 
icons/del ete_config.gif. (You need to have copied the red “x” graphic into the 
icons directory of StickyNotesView project before you try to run the plug-in.) 
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Now you are ready to put the delete code into the new class file you have 
created. See Example 8-15. 

This new class identifies the current view, and issues the deleteNotes() call to 
delete all sticky notes assciated with it. 

Example 8-15 Sticky Notes ViewDelete class 
package sti ckyNotesVi ews; 

import org.ecl ipse. j face. acti on. IAct ion; 
import org.eclipse.jface.dialogs.MessageDialog; 
import org. eel i pse. j f ace. vi ewers. ISelect ion; 
import org. eclipse. swt. widgets. Shell ; 
import org. eclipse. ui .IViewActionDelegate; 
import org. eclipse. ui .IViewPart; 
import org. eclipse. ui .IWorkbench; 
import org. eclipse. ui . IWorkbenchPage; 
import org. eclipse. ui . IWorkbenchWi ndow; 
import org. eclipse. ui .PlatformUI; 

import sti ckyNotesVi ews .views . Sti ckyNotesVi ew; 

public class Sti ckyNotesVi ewsDelete implements IViewActionDelegate { 

private Shel 1 shel 1 ; 

@0verride 

public void init(IViewPart view) {} 

POverride 

public void run(IAction action) { 
if (MessageDialog 

.openConfi rm(shel 1 , "Comfirm Delete", 

"Are you sure you want to permanently delete all 
sticky notes?") == true) { 

IWorkbench workbench = PI atformlll .getWorkbench() ; 

IWorkbenchWi ndow window = workbench. getActiveWorkbenchWindow() ; 
IWorkbenchPage page = window. getActivePage() ; 

IViewPart sampleView = (IViewPart) page 

.findView (" sti ckyNotesVi ews. views. Sti ckyNotes View" ) ; 

( (Sti ckyNotesVi ew) sampleView) .del eteNotes () ; 


POverride 

public void selectionChanged(IAction action, ISelection selection) {} 
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8.5.4 Adding extension points and code for Save View Action 


We need to create the extensions and code that saves a sticky notes list to a .csv 
file so that it can be saved across starts of CICS Explorer. 

If it is not already open, double-click the MANIFEST.MF object in the package 
explorer, and select the Extensions tab in the view. We are going to add an 
exention to the org.eclipse.ui.vewActions plug-in. Click Add, and select the 
org.eclipse.ui.vewActions plug-in. Now we can add our new View Actions. 

Right-click the org.eclipse.ui.vewActions object in the extensions list, and select 
New viewContribution (Ssee Figure 8-4 on page 262). 



Call the new viewContribution StickyNotes, and give it a target ID of 
StickyNotesView. 

Right-click your new StickyNotesviewContribution2, and select New ->• action. 
Give this action an ID of StickyNotes. action2. You are prompted for the name of 
the class that is going to execute the new action. Click class to create the new 
class in the stikyNotesView package, and call it 

stickyNotesViews.StickyNotesViewsSave. (We create this class and add it to the 
stickyNotesViews package shortly.) 
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Next, we are going to add a graphic to the toolbar, which the user can click to 
delete all the sticky notes. Rright-click the StickyNotesviewContribution2 again, 
but this time select New ->• Menu. Give the new menu a name of 
StickyNotes.menu2. In the path box, enter additions, and in the icon box, add 
i cons/save. gi f (you need to have copied the diskette save graphic into the icons 
directory of StickyNotesView project before you try to run the plug-in). 

You are now ready to put the save code into the new class file you have just 
created. See Example 8-16. 

This new class identifies the current view, and then issues the saveNotes () call to 
save all sticky notes associated with it to a .csv file in the Eclipse workspace. 

Example 8-16 StickyNotesViewSave class 
package stickyNotesViews; 

import java.io. Unsupported Encoding Except ion; 

import org. eel ipse. j face. acti on. IAct ion; 
import org.ecl ipse. j face. dialogs. Dialog; 
import org.ecl ipse. j face. dialogs. II nputVal idator; 
import org.ecl ipse. j face. dialogs. I nputDialog; 
import org.ecl ipse. jface. viewers. ISelection; 
import org.ecl ipse. swt. widgets. Shel 1 ; 
import org.ecl ipse. ui .IViewActionDelegate; 
import org.ecl ipse. ui .IViewPart; 
import org.ecl ipse. ui .IWorkbench; 
import org.ecl ipse. ui . IWorkbenchPage; 
import org.ecl ipse. ui . IWorkbenchWi ndow; 
import org.ecl ipse. ui .PartlnitException; 
import org.ecl ipse. ui .PlatformUI; 
import org.ecl ipse. ui .part.ViewPart; 

import sti ckyNotesVi ews .views . StickyNotesView; 

public class Sti ckyNotesVi ewsSave implements IViewActionDelegate { 

private Shel 1 shel 1 ; 
private String notetext; 

QOverride 

public void init(IViewPart view) {} 

QOverride 

public void run(IAction action) { 

String dial ogT i t 1 e = "Save Sticky Notes"; 
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String dialogMessage = "input CSV FILE name (Extention(.csv) is 
automatically added.) 

String initialValue = 

InputDialog inputdialog = new InputDialog(shel 1 , dialogTitle, 
dialogMessage, initialValue, new IlnputVal idator() { 
QOverride 

public String isVal id(String newText) { 
if (newText. length () == 0) { 
return "input filename."; 

} else { 

notetext = newText; 
return nul 1 ; 


}); 

if (inputdialog. open() == Dialog. OK) { 

IWorkbench workbench = PlatformUI.getWorkbench() ; 
IWorkbenchWindow window = 
workbench.getActiveWorkbenchWindow() ; 

IWorkbenchPage page = window. getActi vePage() ; 
try { 

ViewPart sampleView = (ViewPart) page 

.f i ndView("sti ckyNotesVi ews . vi ews . St i ckyNotesVi ew") ; 
if (sampleView == null) { 

sampleView = (ViewPart) page 

.showView("sti ckyNotesVi ews. views. St i ckyNotesVi ew") ; 

} 

( (Sti ckyNotesVi ew) sampl eVi ew) . saveNotes (notetext) ; 


} catch (PartlnitException e) {e.printStackTraceQ ; 
} catch (UnsupportedEncodingException e) { 
e.printStackTrace() ;} 

} 


U 

} 


} 

QOverride 

public void selectionChanged(IAction action, ISelection selection) 
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If you have copied the images into the icon directory, we are now ready to test 
our new plug-in. Right-click the the resource to which you want to add a sticky 
note. For this test we are using a file. See Figure 8-6. 



Figure 8-6 Add sticky note to file 
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This opens a box to add the description for the sticky note. See Figure 8-7. 



Figure 8-7 Sticky note description 
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You see the note display in the sample view shown in Figure 8-8. 



Figure 8-8 New sticky note added 
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Save this note to a CSV file. Click the disk on the window (denoted by the red 
arrow in the bottom right of the figure) as shown in Figure 8-8 on page 269. 
When clicked, you get the text box shown in Figure 8-9. 



Figure 8-9 Save Sticky note as CSV file 
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You can also delete the sticky if you want. To do so, click the red X next to the 
save sticky note to CSV file, you get the message shown in Figure 8-10. 



If you select OK the sticky note is deleted. 
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Implementing a CEBR view 
in CICS Explorer 


In this chapter we look at how you can extend the functionality provided by the 
Operations view of the CICS Explorer, to implement a CEBR-like interface which, 
when you have right-clicked a TS queue, allows you to view the contents of that 
queue. 

► The skill profile of the person who implemented this sample is a CICS 
Systems Programmer who knows only what is in Chapter 5 of this book (And 
a bit of Chapter 4), with no real experience with Java other than a bit of 
playing around with Java primer material and the samples you find earlier in 
this book. 

► The author found that with the help of searching on the Web, and timely 
interventions from a colleague familiar with Java who was also working on this 
Redbooks publication, the author managed to implement the sample. 

► The author adopted a top-down approach to this sample. The starting point 
was a new interface the author wanted to achieve using CICS Explorer. The 
author designed the user interface, and then looked at the user interface code 
the author had to write in Eclipse. The author then looked at the code required 
in our new plug-in to connect to CICS and retrieve the TS Queue. Finally, the 
author wrote the backend code CICS TS code to retrieve the TS queue 
records and return them to his new plug-in. 


© Copyright IBM Corp. 2010. All rights reserved. 
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9.1 The specification for your CEBR view 


If you start your CICS Explorer, and connect to the target CICS WUI region, then 
left-click the Operations tab in the action bar, and select Queues ->■ TS Queues, 
you get a view like Figure 9-1 , showing all the TS queues known in the CICSPlex 
scope within which you are working. 
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Figure 9- 1 CICS Explorer view of TS queues 


If you right-click one of the TS queues shown in the list, CICS Explorer presents 
you with two possible actions: Open or Delete. Wouldn’t it be nice if there were ? 
To achieve a third option, Browse, which allows you to browse the contents of 
the queue , you are must create a new Eclipse plug-in. This plug-in has two 
Eclipse user interface objects: 

► View 

This object displays the records in your TS queue 

► Pop-up menu 

This object gives the option of displaying the new TS queue browse view 

Use the wizard provided by Eclipse to create a template for your new plug-in. 
After you have created the template, add the code required to: 

► Retrieve the name of the queue to be browsed. 

► Build an HTTP request to invoke a CICS TS Cobol program that retrieves the 
contents of the requested TS queue and handle the HTTP response 
containing the contents of TS queue. 

► Display the contents of the TS queue in a new CEBR view. 
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9.2 Using the wizard to create your new plug-in 


Start your Eclipse development environment, and select File -» New Project. 
Select Plug-in Project, and click Next. 

Name your new project BrowseTSQueue and click Next. You are prompted to 
select a template to use for this project (Figure 9-2). This time you are going to 
be more specific about what kind of plug-in you want. Select Custom Plug-in 
wizard and click Next. 



Figure 9-2 Create custom plug-in template 
Your plug-in provides the following advantages: 

► Manage a pop-up menu that allows a TS queue to be selected for browsing 

► Create the view in which the contents of the TS queue are shown. 

Check the View and Pop-up Menu boxes and click Next. 
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The wizard presents you with the sample pop-up menu to ask for more 
information about the pop-up menu. It needs to know the class that defines the 
object to be managed by your pop-up menu. In this case, the Target Object’s 
class is the Explorer class used to manage TS queues: 
com. ibm.cics. model .ITSQueue. 

Name your new class BrowseTSQueue and give suitable names for the submenu 
name and action label, as shown in Figure 9-3, and click Next. 



Figure 9-3 TS Queue Browse sample pop-up menu 


The wizard presents you with the Main View Settings panel. Select appropriate 
names (it is suggested to specify what kind of class you are creating in the name, 
so call this Action class BrowseTSQueueAction), and click Finish. 


Note: On the subject of appropriate names, when you have more than one 
class in your plug-in (here we have an Action and a View), make sure the 
name you choose for your class uniquely identifies that class within your 
plug-in. Otherwise, you might have to manage two different classes with the 
same name that reference each other, which creates complications. 


The wizard creates the plug-in and presents us with the overview editor view for 
our new plug-in BrowseTSQueue. 

At this point, although you have not written any new code yet, run your 
BrowseTSQueue plug-in to see what it does. 

In the Package Explorer view on the left side of the workspace, right-click the 
BrowseTSQueue package and select Run as -> Eclipse Application. 
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A new instance of Eclipse starts with the new plug-in installed. If it has not 
already started with the CICSPlex SM perspective, click Window ->• Show 
View CICS Explorer. Then choose your scope by selecting the CICSPlex or 
CICS region you want to look at in the left pane, and select Operations -> 
Queues ->• TS Queues. Right-clicking one of the TS Queues in this list displays 
a new option in the pop-up menu, as shown in Figure 9-4. 



You have created your desired GUI interface without the need to write a single 
line of code. Select TSQueueBrowse -> Browse TS Queue to see Figure 9-5. 



Figure 9-5 Dummy action for TSQueue Browse plug-in 

You now have to write the code to turn this dummy action into your desired 
function. 
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9.3 Coding your TSQueue Browse plug-in 


Now comes the tricky part. You need to modify the code generated by Eclipse to 
implement your TS Queue Browse function. Remember, there are two objects 
you are working with: 

► TS Queue Browse view 

► TS Queue Browse pop-up action 

9.3.1 Adding code to the TSQueue Browse pop-up menu 

You need to modify the pop-up menu to do two things: 

► Remember which TS queue the user has clicked so that we can use this 
information to retrieve the contents of that queue. 

► Create the TS queue Browse view that displays the contents of the TS queue 

Browse TS Queue pop-up menu function 

In the Explorer package, expand the src folder and double-click the java source 
file BrowseTSQueueAction.java in the browsetsqueue.popup.actions package. 
The Java editor view displays. Double-click the BrowseTSQueueAction.java tab 
to get a full window edit session. 

Change the selectionChangedQ method 

The method you modify to remember which TS queue you are working with is the 
sel ecti onChanged () method. This method is invoked each time the user 
right-clicks a TS queue in the Explorer TS Queue view. Replace the no-op 
method that is generated by Eclipse with the code in Example 9-1 . 

Example 9-1 Browse TSQueue pop-up menu selectionChanged method 
public void selectionChanged(IAction action, ISelection selection) 

{ 

tsqueue = (ITSQueue) ((StructuredSelection) 
selection) .getFirstElement(); 

} 


Eclipse flags errors when you put this code in. This is because you need to 
declare this plug-in’s dependency on the relevant CICS Explorer object (in this 
case the ITSQueue object). 

If you are unsure about the name of the CICS Explorer class you need to use to 
manipulate your CICS object, use the Navigator tab on the workspace menu bar 
to help locate it. 
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Click the Navigator tab in the workspace action bar, and select Open Type. In the 
pop-up menu that displays, enter string com.ibm.cics. Eclipse presents you 
with a list of all the Java classes it has found in packages beginning with that 
name. When you are working with classes that manipulate CICS Explorer 
objects, you usually are working with the interface for those objects, so it is a 
good idea to enter the string string com.ibm.cics.i into the search field. You 
get a list that probably contains the object you want to manipulate. In our case, 
we are going to be working with the ITSQueue interface, as in Figure 9-6. 



Figure 9-6 Finding the right TS Queue object using the Eclipse Navigator 

We have now identified the object we want to work with. We can start modifying 
the copied code to work with TS queues. 
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In the Package Explorer view, double-click the pi ugi n . xml file of the 
BrowseTSQueue project to open the overview editor, and click the Dependencies 
tab. Click Add if the Required plug-ins pane, and enter the name of the CICS 
Explorer plug-in which contains the ITSQueue object com. ibm.cics. model 

Press Ctrl+S to save the change, and double-click BrowseTSQueue.java view 
to return there. If you pass the cursor across the ITSQueue object, Eclipse offers 
to generate the import statement for you. Click this option, and the error 
associated with ITSQueue disappears. If you pass the cursor across the 
StructuredSelection object, you see that you have a similar problem. Eclipse 
offers to add the import statement because it already knows about the package 
that contains this class. Ask Eclipse to do the necessary import. 

Finally, note that the tsqueue variable has not been previously declared. Because 
you need to access this variable across several different methods, it needs to be 
declared at the object level, and not at the method level. Add the declaration for 
tsqueue just after the class definition as shown in Example 9-2. 

Example 9-2 Declaration for global variable tsqueue 

public class BrowseTSQueue implements IObjectActionDelegate { 

private Shel 1 shel 1 ; 
private ITSQueue tsqueue : 


Change the run() method 

The run method of your BrowseTSQueue pop-up action object is invoked when 
the user has clicked the Browse TS queue action in the pop-up menu. Replace 
the default code (which outputs the text shown in Figure 9-5 on page 277), with 
code that displays the Browse TS Queue view. Replace the default code with the 
code shown in Example 9-3 on page 281 . 

You see that there are errors associated with various objects, which Eclipse can 
resolve if you place the cursor over the error and select the appropriate import 
option. The only error that you cannot resolve in this way is the error associated 
with the populateInformation() method of the BrowseTSQueue view object. 
You have not yet defined this method, so this is normal (you define this method 
shortly). 
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Example 9-3 run method of BrowseTSQueue pop-up action object 
public void run(IAction action) { 

final IWorkbenchPage page = 

PI atformlll .getWorkbench() .getActi veWorkbenchWi ndow() .getActi vePage() ; 

try 

{ 

IViewPart view = 

page. showView("browsetsqueue. views. BrowseTSQueue" ) ; 

((BrowseTSQueueView) view) .populatelnformation(tsqueue) ; 

} 

catch (PartlnitException e) { e.printStackTrace() ; } 


Press Ctrl+S to save your changes, and close the pop-up action package 
BrowseTSQueueAct ion. java. 

You have now made all the modifications to the Browse TSQueue pop-up action 
menu object. The next step is to add the corresponding code in the Browse 
TSQueue view object. 

Add code to the Browse TSQueue view object 

Double-click the BrowseTSQueueView. java object in the browsetsqueue.views 
package to open an edit session. You are going to add code to do the following 
tasks: 

► Ask to always be notified when an action is performed 

► Populate the view with the contents of the requested TS Queue 

► Show the populated view 

Update ViewContentProviderQ method 

This method is responsible for providing objects to the associated view. In our 
case, the TS queue data is held in an array of strings, which are accessible 
globally throughout the class. The popul atelnformati on () method calls CICS 
and puts the TS queue records into a global string array variable tsrecord, which 
is accessed through this method. Example 9-4 on page 282 shows the string 
array tsrecord being returned to the caller by this method. 
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Example 9-4 ViewCon ten tProvIderQ method of Browse TSQueue View class 

class ViewContentProvider implements IStructuredContentProvider { 
public void inputChanged(Viewer v. Object oldlnput. Object 
newlnput) { 

} 

publ ic void disposeQ { 

} 

public Object [] getEl ements (Object parent) { 
return tsrecord; 

} 

} 


Add init() method 

You are going to add code to your view object to ensure that whenever an action 
is performed on a TS queue, you update the TS queue contents so that they are 
current. This is done by creating a Listener at the time your view object is 
created. 

By default, Eclipse does not generate an i ni t method for a view object, as it is 
implicit. However, in this case, you are adding function to be executed after the 
implicit init (what is termed a super. init method). You add code to create a 
SelectionListener for your view. 

Each time a TS queue browse view is opened, Eclipse adds a selection listener 
to that view, to wait for selection events. When an object is selected in the TS 
queue browse view, the inline selectionChanged() method coded in 
Example 9-5 is invoked. 

Example 9-5 BrowseTSQueue view object super.init method 
@0verride 

public void init(IViewSite site) throws PartlnitException 

{ 

super. init(site) ; 

// Add a selection listener to look for when people click TSQueue 
entries 

// in the main TSQueue view and then populate this view with their 
contents 

s ite. get Page () .addSelectionListener(new ISelectionListener() 

{ 

QOverride 

public void selectionChanged(IWorkbenchPart argO.ISelection 
selection) 

{ 
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if (!selection.isEmpty()) 

{ 

Object firstElement = ((StructuredSelection) 
selection) .getFirstElement(); 

if (firstElement instanceof ITSQueue) 

{ 

final ITSQueue tsqueue = (ITSQueue) firstElement; 
populatelnformation(tsqueue) ; 


} 

}); 


Note: This selectionChanged() method is unrelated to the pop-up action 
selectionChanged() method discussed in “Change the selectionChanged() 
method” on page 278. The methods have the same name but they are for 
different objects. 


Because this selectionChanged() method is driven for any action requested in 
your view, it checks to see if the requested action is for a TS queue object, and if 
so, refreshes the TS queue contents by invoking the populateInformation() 
method described in the following section. 

Add populate! nformationQ method 

This is the key method of your new implementation. It is here that you call CICS 
TS to retrieve the contents of the TS queue being processed. This method 
performs the following tasks: 

► Build an HTTP Request to send to CICS TS 

► Process the HTTP response containing the TS queue records 

► Make the processed records available to the other methods of the Browse TS 
queue view object. 
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Because the call to CICS TS might take time to complete, it is executed 
asynchronously, on a background thread. This method is shown in Example 9-6. 

Example 9-6 populatelnformationQ method 


public void populateInformation(final ITSQueue tsqueue) { 

Job job = new Job("MyJob") { 

POverride 

protected IStatus run(final IProgressMonitor monitor) { 
monitor.beginTask("myJob", IProgressMonitor .UNKNOWN ) ; 
I0(monitor, tsqueue) ; 

Display.gefDe/auZf () .asyncExec(new RunnableQ 

{ 

public void run() 

{ 

// Do your GUI updates here 
GUI () ; 

} 

}); 

monitor. done() ; 


return Status .OKJTATUS; 

} 


job.schedule() ; 


To make it easier to split out the code that needs to execute asynchronously, the 
function that actually makes the call to CICS has been separated into a routine 
called 10 () and a code that communicates with the user put into a method called 
GUI (). These two method calls are bracketed by calls associated with a job 
object (which separates them out into a separate job for execution on a separate 
thread) and a monitor object used to track the progress of the job (which 
generates a little progress bar at the foot of the workspace). See Figure 9-7 


: My Job [■ 1 ^ 

Figure 9-7 Eclipse Progress Bar 

This separation of 10 and GUI routines is suggested when working with CICS 
Explorer. 
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Note: In our testing, the access to the CICS back-end application was so fast 
that the progress bar associated with the monitor object never got the chance 
to appear unless we trapped the alias transaction with CEDF. 


In Example 9-7 we can see the 10 () method, which is invoked by 
populateInformation(). In Example 9-7 we see the call to CICS over an HTTP 
connection using the classes supplied in java.net. 

Example 9-7 IO() method called by populatelnformation() 

void 10 (f i nal IProgressMonitor monitor, final ITSQueue tsqueue) 

{ 

int length = tsqueue. getItemCount() . i ntVal ue() ; 
tsrecord = new Stri ng [1 ength+1] ; 

URL url = null ; 

String tsname = tsqueue. getName() ; 

//Identify the HTTP connection to the target CICS Web Support 
appl i cation 

//with the URL expected by CICS Web Support 
try { 

url = new URL("http://9. 12.4.74:2404/CICS/CWBA/CEBRWEB") ; 

} catch (Mai formedURLException el) { 

// T0D0 Auto-generated catch block 
System. out. println("Entered populatelnformation" + 
el.getMessageO) ; 

} 


// Set up connection to the target CICS Web Support application 
// this particular application expects a method of POST. 
HttpURLConnection uric = null; 
try { 

uric = (HttpURLConnection) url .openConnection() ; 
try { 

url c.setRequestMethod("POST") ; 

} catch(Protocol Exception e) 

{ throw new Exception("Shouldn't happen - doesn't support POST 

???".e); 

} 


// Build the body of the HTTP POST request. 

// this particular application expects one input field 
TSOUEUE= tsqname 

url c.setDoOutput(true) ; 
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url c.setDoInput(true) ; 

url c.setllseCaches(fal se) ; 

url c.setAl lowllserInteraction(fal se) ; 

OutputStream out = urlc.getOutputStream() ; 

// Send the HTTP Request to CICS 
try { 

String outputstring = "TSQUEUE=" + tsname; 
out.write(outputstring.getBytes()) ; 
out.fl ush() ; 

} catch(IOException e) { 

throw new Exception("IOException while posting data"); 
} finally { 

if (out ! =nul 1 ) 
out.close(); 

} 

// Read the response returned by CICS 
InputStream in = url c.getInputStream() ; 

BufferedReader rd = new BufferedReader(new 
InputStreamReader(in)) ; 

String line; 
int j = 0; 

while ((line = rd.readLine()) != null) { 
tsrecord[j] = line; 
j+=l; 

} 

rd.close() ; 

} catch(Exception e) { 

System. out. println("Exception here! ! ") ; 
e.printStackTrace() ; 

} 

} 


The code handling the HTTP request and response is standard Java for 
manipulating HTTP. 
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The HTTP request sent to CICS by our plug-in is shown in Example 9-8. 

Example 9-8 HTTP POST request to invoke program CEBRWEB 

POST /CICS/CWBA/CEBRWEB HTTP/1.1 
Cache-Control: no-cache. . Pragma: no-cache 
User-Agent: Java/1.6.0 
Host: 9.12.4.74:2404 

Accept: text/html , image/gif, image/jpeg, *; q=.2, */*; q=.2 
Connection: keep-alive. 

Content-type: appl ication/x-www-form-url encoded 
Content-Length: 13 

TSQUEUE=STEVE 


The HTTP response returned by CICS looks like Example 9-9. 
Example 9-9 HTTP response 

HTTP/1.1 200 OK.. Date: Thu, 22 Oct 2009 19:17:38 GMT 
Server: IBM_CICS_Transaction_Server/4. 1.0(z0S) 
Content-Length: 000000000000412 
Connection: Keep-Alive 

ABCD 

EFGH 

IJKL 

MN0P 

QRST 


The TS queue records are delimited by a CRLF sequence at the end of each 
record (as it stands, this sample only works for TS queues that contain text). 

The loop at the end of the 10 () method loops through the body of the HTTP 
response, and writes each line (TS queue record) out to a separate string in our 
ts record string array. 

The TS Browse view itself is only updated when the GUI () method is invoked to 
perform a viewer. refreshQ call. 
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In Figure 9-8 we have selected Operations Queues ->• TS Queues. When we 
click the CICSPlex in the left pane to set the context, CICS Explorer populates 
the view with information about TS queues in the CICSPlex. 



When you click the CICSplex name on the left, CICS Explorer populated the 
upper TS Queue operations view with the details of the TS queues that exist in 
CICSPlex EPRED. The Browse TS queue pane is still empty because we have 
not yet selected a TS queue to browse. If we now right-click one of the TS 
queues in the upper-center pane, and choose the option TS Queue Browse 
Browse TS Queue, the lower-center pane is populated with the records of the 
selected TS queue (Figure 9-9 on page 289). After the Browse TS queue is 
displayed left-click the TS queue you are interested in to see what it contains. 
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9.4 CICS TS Application Specification 

The back-end application that is invoked by the CICS Explorer Browse TS Queue 

plug-in is a CICS Web Support COBOL SPI program that does the following: 

► Parses the HTML forms data sent by CICS Explorer to extract the name of the 
TS Queue to be returned 

► Performs an EXEC CICS INQUIRE TS QUEUE to retrieve details about the 
requested TS queue 

► Executes a loop to retrieve the items in the TS queue and adds them to the 
body of the HTTP response returned to CICS Explorer 

► Returns an HTTP response containing the TS Queue contents to CICS 
Explorer 

The CEBRWEB program is supplied with the additional materials for this book. 
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Note: We have a couple of “To Do” items for this sample, which we did not 
have time to implement 

► Support for exchanging and displaying binary data (between the 
CEBRWEB program and the BrowseTSQueue plug-in) 

► Ability to rewrite one of the records in the queue 

If you want to implement any of them, you can download the Eclipse 
workspace containing the existing code and add to the plug-in, and perhaps 
share your new plug-in with the CICS Explorer community through the CICS 
Explorer forum. 


9.5 Extending the connection preferences panel 

In this section, we extend the CICS Explorer connection preferences panel to 
input connection details for the CICS service. This replaces the existing hard 
coded values in the example code. 

9.5.1 Creating the extension points 

Starting with the BrowseTSQueueView workspace, double-click plugin.xml and 
select the Extensions tab. Clear the Show only extension points from the 
required plug-ins check box, select com. ibm.cics. core. comm, and click 
Finish. 

When prompted with the message “Do you want to add plug-in 

com. ibm.cics. core. comm, declaring the connections extension point, to the list of 

plug-in dependencies?” select Yes. 

Repeat the same for extension com.ibm.cics.core.ui.connectionCustomizers. 

Click the plugin.xml tab and observe that the extensions have been added to the 
bottom of the XML. 

Replace the content of the com.ibm.cics.core.comm extension with 
Example 9-10 on page 291. 
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Example 9-10 The connections extension point 


<extensi on poi nt=" com. i bm. ci cs . core . comm. connect i ons "> 
<category abbreviatedName="CEBR" 

connectionType="browsetsqueue. connect ion. IWebConnection" 
id="browsetsqueue. connection. category" 
name="CEBR Category"> 

</category> 

<connecti on category="browsetsqueue . connection . category" 
cl ass="browsetsqueue. connecti on .WebConnecti on" 
id="browsetsqueue. connect ion. connect ion" 
name="CEBR Web Connecti on"> 

</connection> 

</extension> 


Replace the content of the com.ibm.cics.core.ui.connectionCustomizers 
extension with Example 9-1 1 . 

Example 9-11 The connectionCustomizer extension point 

<extensi on poi nt="com. i bm. ci cs . core. ui .connecti onCustomi zers"> 
<customizer 

cl ass="browsetsqueue. connecti on. Connecti onCustomi zer" 
connectionId="browsetsqueue. connect ion. connect ion" 
id="browsetsqueue. connect ion. customizer" 
name="CEBR Web Customizer"> 

</customizer> 

</extension> 


Press CTRL+S to save the updates. You have now done enough for your new 
connection type to be shown in the CICS Explorer connection preferences. You 
can observe this by running the BrowseTSQueueView application and selecting 
Windows ->• Preferences ->• Connections. From the Connection Type drop 
down mneu select CEBR Web Connection. Input the correct values for your 
connection and click Apply. The connection information is now saved. 

Click the Connect button and you see that nothing happens. This is because you 
have not yet created the classes that handles the connection activity. This is what 
we do next. 
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9.5.2 Creating the connection classes 


Next, we can create the classes that provide a connection to he back-end 
service. We need: 

► An interface that is referenced by the CICS Explorer classes when handling 
the connection 

► A class that connects directly with the back-end service, and implement the 
interface above 

► A class that exposes the connection details on the connection preferences 
panel 

► A class that provides a bridge between CICS Explorer and the class that 
connects to the back end service above. 

IWebConnection interface 

Back in your Eclipse development environment create a new interface with the 
package browsetsqueue. connection and name IWebConnection. The interface 
needs to extend com. ibm.cics.core. comm. IConnection. This interface matches 
up with the connectionType entry in the category element of your pi ugin.xml . 

You do not need to specify any methods in the interface. The interface is used by 
proxies under the covers by the CICS Explorer and Java proxies only work with 
interfaces. The IWebConnection interface is shown in Example 9-12. 

Example 9-12 The IWebConnection interface 
package browsetsqueue. connect ion; 

import com. ibm.cics.core. comm. IConnection; 

public interface IWebConnection extends IConnection {} 


Important: In order for the CICS Explorer to work with the IWebConnection 
interface, you must make its package visible from the plug-in. To do this 
double-click pi ugi n . xml and select the Runtime tab. Click the Add button next 
to Exported Packages and select browsetsqueue.connection from the list. 
Press CTRL+S to save the changes. 

The package is now added to the export list and is visible to any Eclipse 
plug-in that chooses to work with it. 
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WebConnection class 

A class is needed to directly deal with the connection to the back-end service. In 
the case of BrowseTSQueueView all that is needed is the ability to store and 
retrieve the host name and port number of the CICS TCPIPService to which the 
view connects. Requests to the service are only made when needed and no 
permanent connection state is maintained. Because of this, the class you use to 
deal with the connection is simple. 

In the same Java package create a class called WebConnection that extends 
com. ibm.cics. core. comm.AbstractConnection and implements 
browsetsqueue.connection.lWebConnection. Eclipse prompts you to add in the 
required unimplemented methods. Move the mouse cursor of the 
WebConnection class name and select Add unimplemented methods. The 
finished version of WebConnection is shown in Example 9-13. 

Example 9-13 The WebConnection class 
package browsetsqueue. connect ion; 


import com . i bm . ci cs . core . comm . AbstractConnecti on ; 
import com. i bm. ci cs . core . comm. Connect i onExcepti on ; 


public 

{ 


class WebConnection extends AbstractConnecti on 
implements IWebConnection 


private boolean connected = false; 


POverride 

public void connect () throws Connecti onExcepti on 

{ 

connected = true; 

} 


POverride 

public void disconnect) throws Connecti onExcepti on 

{ 

connected = false; 

} 


POverride 

public boolean isConnected() 

{ 

return connected; 

} 
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ConnectionCustomizer class 

Looking at pi ugin.xml , the ConnectionCustomizer extension references a class 
under the customizer element. This class deals with modifications to the 
connection preferences panel specific to your connection type. Even if you 
choose to use the default entry fields on the connection preferences panel you 
must still use the ConnectionCustomizer extension because this causes your 
connection to get instantiated. 

Alongside the above classes create one called ConnectionCustomizer that 
implements the interface com. ibm.cics. core. ui . IConnectionCustomizer. Make 
sure you add the necessary methods that the IConnectionCustomizer interface 
requires you to implement. 

The createControl () method provides an opportunity to extend the connection 
preferences panel with additional widgets. For the CEBR Web connection we 
add a Label widget that explains the purpose of this connection type. 

Example 9-14 shows the finished version of the ConnectionCustomizer class. 

Example 9-14 The ConnectionCustomizer class 
package browsetsqueue. connect ion; 

import org. eel ipse. core. runtime. CoreException; 

import org .eel i pse . core . runtime . IConf i gurati onEl ement ; 

import org. eclipse. swt. SWT; 

import org. eel ipse. swt. widgets. Composite; 

import org. eel ipse. swt. widgets. Label ; 

import com. i bm. ci cs . core . comm. Connect i onConfi gurati on ; 

import com. ibm.cics. core. ui .IConnectionCustomizer; 

public class ConnectionCustomizer implements IConnectionCustomizer 

{ 

@0verride 

public void createControl (Composite argO) 

{ 

Label label = new Label (argO, SWT./VO/Vf); 
label .setText("Connect to TCPIP service for " + 

"getting TSQueue contents"); 

} 


@0verride 

public boolean performOkQ { return true; } 

@0verride 

public void setConfiguration(ConnectionConfiguration argO) 

U 
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POverride 

public void setDirty(boolean argO) {} 

POverride 

public void setlnitial izationData(IConfigurationElement config. 
String propertyName, Object data) throws CoreException {} 

} 


Running the example and opening the connection preferences panel gives the 
CEBR Web information, as shown in Figure 9-10. 



Figure 9-10 Connection preferences panel with CEBR Web Connection details 

If you fill in the fields and click Connect, you see that nothing happens. This is 
due to the way the CICS Explorer interacts with connection objects. To get make 
this function work, further objects need to be created. 

WebConnectable class 

Create a new Java class called WebConnectabl e. The new class must implement 
the interface com.ibm.cics.core.comm.lConnectable and provide 
implementations of all of its methods. The WebConnectable class provides a 
bridging mechanism for the CICS Explorer to work with the WebConnection 
object. Only one instance of it can exist in the system, so the relevant code must 
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be in place to enforce this. The technique for creating a singleton of an object is 
as follows: 

1 . Create a static instance of the object inside its own class. 

2. Define a private constructor such that no one other than the class itself can 
instantiate it. 

3. Create a public static method called getDefault() that returns the static 
instance of the class defined in step 1 . 

Example 9-15 shows the finished version of the WebConnectable class. 

Example 9-15 The WebConnectable class 
package browsetsqueue. connect ion; 

import com. i bm. ci cs . core . comm. Connect i onExcepti on ; 
import com. ibm.cics. core. comm. IConnectable; 
import com. i bm. ci cs . core . comm. IConnectabl eLi stener; 
import com. ibm.cics. core. comm. IConnect ion; 

public class WebConnectable implements IConnectable 

{ 

// Singleton instance of this class 
private static WebConnectable WebConnectable 
= new WebConnectable(); 

// Restrict others from instantiating this class 
private WebConnectableQ {} 

// Return the singleton instance 
public static WebConnectable getDefaultQ 
{ return WebConnectable; } 

private IConnection webConnection; 

@0verride 

public void addListener(IConnectableListener argO) {} 

@0verride 

public void disconnect) 

{ 

try { webConnection. disconnect) ; } 
catch (ConnectionException e) 

{ e.printStackTrace() ; } 
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} 


POverride 

public IConnection getConnection() 

{ return webConnection; } 

POverride 

public Class<IWebConnection> getConnectionType() 
{ return IWebConnection.class; } 

POverride 

public boolean isConnected() 

{ return webConnection. isConnected() ; } 

POverride 

public void setConnecti on (IConnection argO) 

{ webConnection = argO; } 


The final step is to register the WebConnectable class with the UlPlugin resource 
manager. This enables the connection preferences panel to work with the object 
when the Connect button is pressed. 


9.5.3 Register WebConnectable with the resource manager 

The WebConnectable class needs to be registered prior to the connection 
preferences panel being shown. One place to do this is the Activator class of 
your plug-in. If you do not have an Activator class, you can do it at static 
initialization of the ConnectionCustomizer class. Example 9-16 shows the 
additional code that is added to ConnectionCustomizer to perform the 
registration. 

Example 9-16 Registering the WebConnectable class with the resource manager 
public class ConnectionCustomizer implements IConnectionCustomizer 
{ 

static 

{ 

UIPlugin.getDe/auZf () 

.setResourceManager("browsetsqueue. connect ion. category", 
WebConnectable. getDe/auZt ()); 

} 
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Next, run the plug-in and click Connect. You see the password dialog box shown 
in Figure 9-11. 



Figure 9-11 The sign-on dialog for your connection 


Note: Because we are not using authentication in this example, the password 
field can be left blank. If you choose to use HTTP basic authentication, this is 
where the appropriate login information is entered. 


Click OK in the dialog box to return to the connection preferences panel. Even 
though it is not easy to see it at this point, you are signed in. 

9.5.4 Viewing sign-on status in the trim bar 

The CICS Explorer has a trim widget at the bottom right of the workspace for 
showing signing status. Figure 9-12 shows the CICS Explorer trim widget. 


9 - wt5c66.itso.ibm.com 

Figure 9-12 The CICS Explorer trim widget 

The CEBR Web Connection can make use of this trim whenever the CEBR view 
is selected. This is done by overriding the get Part Property () method of your 
view. Add the code shown in Example 9-17 on page 299 to BrowseTSQueueView to 
make use of the trim widget. 
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Example 9-17 Override getPartPropertyQ to make use of the trim widget 


public String getPartProperty(String key) 

{ 

if (IConnectionCategory. class. getName() .equals(key)) 
return "browsetsqueue. connect ion. category"; 
else return super. getPartProperty(key) ; 


Next, run the plug-in, sign-in, and open the TSQueue Browse view. The trim 
widget is updated to show your new connection. Figure 9-13 shows the trim 
widget with a connection to the ITSO systems. The green icon indicates that the 
connection is active. 


» - ITSO Connection 

Figure 9-13 The CEBR Web Connection widget 


9.5.5 Using the CEBR Web Connection 

At this point we have created the object for managing the connection to the 
CEBR service in CICS. We next update the TSQueue Browse view to make use 
of the connection. 

The TSQueue Browse view must signify its interest in the CEBR Web 
Connection to work with it. This is done by creating an class of type 
IResourceManagerListener and registering it with the resource manager. After 
the listener is registered it receives notifications about the connection status. Add 
the code in Example 9-18 to BrowseTSQueueView as an inner class for receiving 
notifications. 

Example 9-18 WebConnectionListener inner class 

private class WebConnectionListener 

implements IResourceManagerListener 

{ 

@0verride 

public void connected(IConnectable argO) 

{ connection = argO.getConnectionQ ; } 

POverride 

public void connecting(IConnectable argO) {} 

POverride 

public void disconnected(IConnectable argO) 
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{ connection = null ; } 


@0verride 

public boolean disconnecting(IConnectable argO) 

{ return false; } 


} 


@0verride 

public void exception(IConnectable argO, 
Exception argl) {} 


Add an IConnection variable to BrowseTSQueueView, as shown in Example 9-19. 
This holds a reference to the connection object that is given to the connected () 
method of the inner class. 

Example 9- 1 9 IConnection instance for holding the connection object 
private IConnection connection : 


You must now register an instance of the WebConnecti onLi stener with the 
resource manager. This is done by adding the code in Example 9-20 to the end 
of BrowseTSQueueView’s init() method. 

Example 9-20 Registering the WebConnectionListener with the resource manager 
UIP1 ugin.getDe fault () 

.addResourceManagerLi stener ( "browsetsqueue . connecti on . category" , 
new WebConnectionListener()); 


Whenever the connection status is modified, the WebConnectionListener 
instance is notified. 


Note: The WebConnectionListener only gets added when the TSQueue 
Browse view is first opened. This implies that if you have signed on before the 
view is opened then you miss the call to the connected () . This is not the case 
however, because the connect () method of the inner class always gets called 
by the resource manager when the view is opened, even if it 10 minutes after 
you have signed on. 


The final stage is to make use of the connection details when retrieving the 
TSQueue contents across HTTP. 
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9.5.6 Updating BrowseTSQueueView to use connection details 


Currently the host name and port number of the CICS service to connect to are 
hard coded in the 10 () method of BrowseTSQueueView. Now that a connection 
is available, the host name and port number need to be replaced with the values 
given to the connection preferences panel. Do this by updating the URL object 
creation in the I0() method so it looks like the code shown in Example 9-21. 

Example 9-21 Creating a URL using the connection object information 

url = new URL("http://" + connection. getHostQ + + 

connection. getPort() + "/CICS/CWBA/CEBRWEB") ; 


If the connection object does not exist (that is, you have not yet signed on to the 
CEBR Web Connection), a NullPointerException occurs when the preceding 
code is run. To prevent this from happening make the call to 10 () conditional on 
the connection object existing and having a valid connection. Do this by 
modifying the call to I0() in the populateInformation() method, as shown in 
Example 9-22. 

Example 9-22 Conditionally calling IO() depending on the connection status 

if (connection != null && connection. isConnectedQ) 

I0(monitor, tsqueue); 


Next, run the plug-in code, sign in, and connect. You can see that the TSQueue 
information is being retrieved as before, but this time it is using the connection 
information you specified in the connection preferences panel. 


Note: The code in the preceding example shows a valid connection even if an 
invalid IP address is entered. An enhancement to this code is to implement a 
ping() method that validates the host name and port information. 


The finished code for this section is in the workspace titled 
BrowseTSQueueWithConnectionPanel. 
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A 


Reference list of CICS SDK 
elements 


This appendix provides the listing of available CICS types, system manager 
actions, definition builders and mutable objects. 
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CICS types 


The following sections are a reference list of CICS SDK CICS types. 

CICS Resources 

► AtomService 

► Bundle 

► BundlePart 

► Captu reSpecification 

► CompletedTask 

► Connection 

► DB2Connection 

► DB2Entry 

► DB2Transaction 

► DBCTLSubsystem 

► DocumentTemplate 

► EventBinding 

► EventProcessing 

► ExtrapartitionTDQueue 

► GlobalDynamicStorageArea 

► IndirectTDQueue 

► IntrapartitionTDQueue 

► IntervalControlRequest 

► IPICConnection 

► JVMCIassCache 

► JVMStatus 

► JVM Pool 

► JVMProfile 

► JVMServer 

► Library 

► LibraryDSName 

► Local File 

► LocalTransaction 

► Pipeline 

► ProcessType 

► Program 

► Region 

► RemoteFile 

► RemoteTDQueue 

► RemoteTransaction 

► RPLList 

► Task 


304 Extend the CICS Explorer: A Better Way to Manage Your CICS 



► TCPIPService 

► Terminal 

► TransactionClass 

► TSModel 

► TSQueue 

► UnitOfWorkEnqueue 

► URIMap 

► WebService 

► WMQConnection 

► WMQConnectionStatistics 

► WMQInitiationQueue 

► XMLTransform 

CICS Definitions 

► AtomServiceDefinition 

► BundleDefinition 

► ConnectionDefinition 

► CorbaServerDefinition 

► DB2ConnectionDefinition 

► DB2EntryDefinition 

► DB2TransactionDefinition 

► DocumentTemplateDefinition 

► DeployedJARFileDefinition 

► EnqueueModelDefinition 

► FileDefinition 

► IPICConnectionDefinition 

► JournalModelDefinition 

► JVMServerDefinition 

► LibraryDefinition 

► LSRPoolDefinition 

► MapSetDefinition 

► PartnerDefinition 

► PipelineDefinition 

► ProcessTypeDefinition 

► ProfileDefinition 

► ProgramDefinition 

► PartitionSetDefinition 

► RequestModelDefinition 

► SessionDefinition 

► TCPIPServiceDefinition 

► TDQueueDefinition 

► TerminalDefinition 

► TransactionDefinition 
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► TransactionClassDefinition 

► TSModelDefinition 

► TypetermDefinition 

► URIMapDefinition 

► WebServiceDefinition 

► WMQConnectionDefinition 

CPSM Definitions 

► CICSRegionDefinition 

► CICSRegionGroupDefinition 

► ResourceDescriptionDefinition 

► ResourceGroupDefinition 


CPSM Managers 

► BatchedRepositoryUpdateRequest 

► CICSplex 

► CMASDetails 

► Event 

► ManagedRegion 

► WLMActiveWorkload 


CSD Definitions 

► CSDGroupDefinition 

► CSDListDefinition 


System manager actions 

► Acquire 

► AddToGroup 

► AllStatistics 

► ARM Restart 

► Backout 

► Cancel 

► Close 

► CloseForce 

► Closelmmediate 

► CloseNoWait 

► CloseWait 
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Commit 

Connect 

Delete 

DeleteShipped 

Deregister 

Disable 

DisableForce 

DisableNoWait 

DisableWait 

Discard 

DisconnectForce 

DisconnectNoWait 

DisconnectWait 

Drain 

Enable 

EndAffinity 

EventProcessing 

Force 

ForceCancel 

ForcePurge 

ForcePurgeJVMCIassCacheAutoStart 

ForcePurgeJVMCIassCacheNoAutoStart 

ForcePurgeTask 

Kill 

KillTask 

Inservice 

Install 

Lock 

NewCopy 

NoRecoveryData 

NotPending 

Open 

Outservice 

Phaseln 

PhaseOut 

PhaseOutJVMCIassCacheAutoStart 

PhaseOutJVMCIassCacheNoAutoStart 

Purge 

PurgeJVMCIassCacheAutoStart 

PurgeJVMCIassCacheNoAutoStart 

PurgeTask 

Rebuild 

Release 

RemoveFromGroup 

ResetTime 
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► Resynchronize 

► Scan 

► SecurityRebuild 

► Shutdownlmmediate 

► ShutdownNormal 

► ShutdownTakeover 

► Start 

► Stop 

► Switch 

► Unlock 


Definition builders 

Here is the list of all available definition builders. All entries that end with the word 
Gen are abstract and cannot be instantiated. Instead you must use one of its 
subclasses. 

► AtomServiceDefinitionBuilderGen 

- AtomServiceDefinitionBuilder 

► BuilderHelper 

► BundleDefinitionBuilder 

► ConnectionDefinitionBuilder 

► CorbaServerDefinitionBuilder 

► DB2ConnectionDefinitionBuilder 

► DB2EntryDefinitionBuilder 

► DB2TransactionDefinitionBuilder 

► DeployedJARFileDefinitionBuilder 

► DocumentTemplateDefinitionBuilderGen 

- DocumentTemplateDefinitionBuilder 

► EnqueueModelDefinitionBuilder 

► FileDefinitionBuilder 

► IPICConnectionDefinitionBuilder 

► JournalModelDefinitionBuilder 

► JVMServerDefinitionBuilder 

► LibraryDefinitionBuilder 

► LSRPoolDefinitionBuilder 

► MapSetDefinitionBuilder 

► PartitionSetDefinitionBuilder 

► PartnerDefinitionBuilder 

► PipelineDefinitionBuilder 

► ProcessTypeDefinitionBuilder 

► ProfileDefinitionBuilder 
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► ProgramDefinitionBuilder 

► RequestModelDefinitionBuilder 

► ResourceDescriptionDefinitionBuilder 

► ResourceGroupDefinitionBuilder 

► SessionDefinitionBuilder 

► TCPIPServiceDefinitionBuilder 

► TDQueueDefinitionBuilderGen 

- ExtrapartitionTDQueueBuilder 

- IndirectTDQueueBuilder 

- IntrapartitionTDQueueBuilder 

- RemoteTDQueueBuilder 

► TerminalDefinitionBuilder 

► TransactionClassDefinitionBuilder 

► TransactionDefinitionBuilder 

► TSModelDefinitionBuilder 

► TypetermDefinitionBuilder 

► URIMapDefinitionBuilderGen 

- AtomURIMapDefinitionBuilder 

- ClientURIMapDefinitionBuilder 

- PipelineURIMapDefinitionBuilder 

- ServerURIMapDefinitionBuilder 

► WebServiceDefinitionBuilder 

► WMQConnectionDefinitionBuilder 


Mutable objects 

► IMutableAtomService 

► IMutableAtomServiceDefinition 

► IMutableBundle 

► IMutableBundleDefinition 

► IMutableBundlePart 

► IMutableCaptureSpecification 

► IMutableCICSDefinition 

► IMutableCICSResource 

► IMutableConnection 

► IMutableConnectionDefinition 

► IMutableCorbaServerDefinition 

► IMutableCPSMDefinition 

► IMutableDB2Connection 

► IMutableDB2ConnectionDefinition 

► IMutableDB2Entry 

► IMutableDB2EntryDefinition 

► IMutableDB2Transaction 
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► IMutableDB2TransactionDefinition 

► IMutableDBCTLSubsystem 

► IMutableDeployedJARFileDefinition 

► IMutableDocumentTemplate 

► IMutableDocumentTemplateDefinition 

► IMutableEnqueueModelDefinition 

► IMutableEventBinding 

► IMutableEventProcessing 

► IMutableExtrapartitionTDQueue 

► IMutableFileDefinition 

► IMutableGlobalDynamicStorageArea 

► IMutablelndirectTDQueue 

► IMutablelntervalControlRequest 

► IMutablelntrapartitionTDQueue 

► IMutablelPICConnection 

► IMutablelPICConnectionDefinition 

► IMutableJournalModelDefinition 

► IMutableJVMCIassCache 

► IMutableJVMPool 

► IMutableJVMProfile 

► IMutableJVMServer 

► IMutableJVMServerDefinition 

► IMutableJVMStatus 

► IMutableLibrary 

► IMutableLibraryDefinition 

► IMutableLibraryDSName 

► IMutableLocalFile 

► IMutableLocalTransaction 

► IMutableLSRPoolDefinition 

► IMutableMapSetDefinition 

► IMutablePartitionSetDefinition 

► IMutablePartnerDefinition 

► IMutablePipeline 

► IMutablePipelineDefinition 

► IMutableProcessType 

► IMutableProcessTypeDefinition 

► IMutableProfileDefinition 

► IMutableProgram 

► IMutableProgramDefinition 

► IMutableRegion 

► IMutableRemoteFile 

► IMutableRemoteTDQueue 

► IMutableRemoteTransaction 

► IMutableRequestModelDefinition 

► IMutableResourceDescriptionDefinition 
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IMutableResourceGroupDefinition 

IMutableRPLList 

IMutableSessionDefinition 

IMutableTask 

IMutableTCPIPService 

IMutableTCPIPServiceDefinition 

IMutableTDQueueDefinition 

IMutableTerminal 

IMutableTerminalDefinition 

IMutableTransactionClass 

IMutableTransactionClassDefinition 

I M utableTransaction Def in ition 

IMutableTSModel 

IMutableTSModelDefinition 

IMutableTSQueue 

IMutableTypeterm Definition 

IMutableURIMap 

IMutableURIMapDefinition 

IMutableWebService 

IMutableWebServiceDefinition 

IMutableWMQConnection 

IMutableWMQConnectionDefinition 

IMutableWMQConnectionStatistics 

IMutableWMQInitiationQueue 

IMutableXMLTransfor 
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View IDs 


Resource views 

► com.ibm.cics.core.ui.view.cicsPlexRepositories 

► com.ibm.cics.core.ui.view.cicsplexes 

► com.ibm.cics.core.ui.view.connections 

► com.ibm.cics.core.ui.view.eventbindings 

► com.ibm.cics.core.ui.view.events 

► com.ibm.cics.core.ui.view.files 

► com.ibm.cics.core.ui.view.regions 

► com.ibm.cics.core.ui.view.tasks 

► com.ibm.cics.core.ui.view.tdqueues 

► com.ibm.cics.core.ui.view.terminals 

► com.ibm.cics.core.ui.view.transactions 

► com.ibm.cics.core.ui.view.tsqueues 


► com.ibm.cics.sm.ui.views.atomServices 

► com.ibm.cics.sm.ui.views.batchedRepositoryUpdateRequests 

► com.ibm.cics.sm.ui.views.bundleParts 

► com.ibm.cics.sm.ui.views.bundles 

► com.ibm.cics.sm.ui.views.captureSpecifications 

► com.ibm.cics.sm.ui.views.cicsstors 

► com.ibm.cics.sm.ui.views.cmasDetails 

► com.ibm.cics.sm.ui.views.completedTasks 

► com.ibm.cics.sm.ui.views.db2Connections 

► com.ibm.cics.sm.ui.views.db2Entries 

► com.ibm.cics.sm.ui.views.db2Transactions 

► com.ibm.cics.sm.ui.views.dbctlsss 

► com.ibm.cics.sm.ui.views.documentTemplates 

► com. ibm.cics.sm.ui.views. eventprocessing 

► com.ibm.cics.sm.ui.views.intervalControlRequests 

► com.ibm.cics.sm.ui.views.ipicConnections 

► com.ibm.cics.sm.ui.views.jvmClassCaches 

► com.ibm.cics.sm.ui.views.jvmPools 

► com.ibm.cics.sm.ui.views.jvmProfiles 

► com.ibm.cics.sm.ui.views.jvmServers 

► com.ibm.cics.sm.ui.views.jvmStatus 

► com. ibm.cics.sm.ui.views. libraries 

► com.ibm.cics.sm.ui.views.libraryDSNames 

► com. ibm.cics.sm.ui.views. pipelines 

► com.ibm.cics.sm.ui.views.processTypes 
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► com. ibm.cics.sm.ui.views. programs 

► com.ibm.cics.sm.ui.views.rpIList 

► com.ibm.cics.sm.ui.views.tcpipServices 

► com.ibm.cics.sm.ui.views.transactionClasses 

► com.ibm.cics.sm.ui.views.tsModels 

► com.ibm.cics.sm.ui.views.unitOfWorkEnqueues 

► com.ibm.cics.sm.ui.views.uriMaps 

► com.ibm.cics.sm.ui.views.webServices 

► com.ibm.cics.sm.ui.views.wImActiveWorkloads 

► com.ibm.cics.sm.ui.views.wmqConnectionStatistics 

► com.ibm.cics.sm.ui.views.wmqConnections 

► com.ibm.cics.sm.ui.views.wmqlnitiationQueues 

► com.ibm.cics.sm.ui.views.xmlTransforms 

Definition views 

► com.ibm.cics.core.ui.view.transactionDefinitions 


► com.ibm.cics.sm.ui.views.atomServiceDefinitions 

► com.ibm.cics.sm.ui.views.bundleDefinitions 

► com.ibm.cics.sm.ui.views.connectionDefinitions 

► com.ibm.cics.sm.ui.views.corbaServerDefinitions 

► com.ibm.cics.sm.ui.views.db2ConnectionDefinitions 

► com.ibm.cics.sm.ui.views.db2EntryDefinitions 

► com.ibm.cics.sm.ui.views.db2TransactionDefinitions 

► com.ibm.cics.sm.ui.views.deployedJARFileDefinitions 

► com.ibm.cics.sm.ui.views.documentTemplateDefinitions 

► com.ibm.cics.sm.ui.views.enqueueModelDefinitions 

► com.ibm.cics.sm.ui.views.fileDefinitions 

► com.ibm.cics.sm.ui.views.ipicConnectionDefinitions 

► com.ibm.cics.sm.ui.views.journalModelDefinitions 

► com.ibm.cics.sm.ui.views.jvmServerDefinitions 

► com.ibm.cics.sm.ui.views.libraryDefinitions 

► com.ibm.cics.sm.ui.views.lsrPoolDefinitions 

► com.ibm.cics.sm.ui.views.mapSetDefinitions 

► com.ibm.cics.sm.ui.views.partitionSetDefinitions 

► com.ibm.cics.sm.ui.views.partnerDefinitions 

► com.ibm.cics.sm.ui.views.pipelineDefinitions 

► com.ibm.cics.sm.ui.views.processTypeDefinitions 

► com.ibm.cics.sm.ui.views.profileDefinitions 

► com.ibm.cics.sm.ui.views.programDefinitions 

► com.ibm.cics.sm.ui.views.requestModelDefinitions 

► com.ibm.cics.sm.ui.views.resourceDescriptionDefinitions 
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► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 

► com.ibm.cics.sm.ui 


.views.resourceGroupDefinitions 

.views.sessionDefinitions 

.views.tcpipServiceDefinitions 

.views.tdQueueDefinitions 

.views.terminal Definitions 

.views.transactionClassDefinitions 

.views.tsModelDefinitions 

.views.typetermDefinitions 

.views.uriMapDefinitions 

.views.webServiceDefinitions 

.views.wmqConnectionDefinitions 
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Additional material 


This book refers to additional material that can be downloaded from the Internet 
as described. 


Locating the Web material 

The Web material associated with this book is available in softcopy on the 
Internet from the IBM Redbooks Web server. Point your Web browser at: 
ftp : //www. redbooks . i bm.com/redbooks/SG247819 
Alternatively, you can go to the IBM Redbooks Web site at: 
ibm.com/redbooks 

Select the Additional materials and open the directory that corresponds with 
the IBM Redbooks form number, SG247819. 


© Copyright IBM Corp. 2010. All rights reserved. 


315 



Using the Web material 


The additional Web material that accompanies this paperbook includes the 
following files: 

File name Description 

CETRTraceWorkSpace.zip CETRTrace sample Eclipse CICS Explorer 
workspace 

OMEGAMON Chapter source code (and project data).zip 

OMEGAMON source code 

Shaylaworkspaces.zip CETRTrace sample Eclipse CICS Explorer 
workspace 

Steveworkspaces.zip CEBR sample Eclipse CICS Explorer workspace 

Workspace_cicsex1.zip Basic Hello World sample Eclipse CICS Explorer 

workspace 

Workspace_cicsex2_20091023.zip 

Hello World sample Eclipse CICS Explorer 
workspace 

Workspace_cicsex6_20091028_fullspec.zip 

Hello World full function sample Eclipse CICS 
Explorer workspace 

Workspace_sticky notes.zip Sticky Notes sample Eclipse CICS Explorer 
workspace 


How to use the Web material 

Create a subdirectory (folder) on your workstation, and unzip the contents of the 
Web material zip file into this folder. 
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Related publications 


The publications listed in this section are considered particularly suitable for a 
more detailed discussion of the topics covered in this book. 


IBM Redbooks 

For information about ordering these publications, see “How to get Redbooks” on 
page 318. Note that some of the documents referenced here might be available 
in softcopy only. 

► CICS Explorer, SG24-7778 


Other publications 

These publications are also relevant as further information sources: 

► Eclipse Building Commercial-Quality Plug-ins , Clayberg and Rubel 
ISBN 0-321 -42672-X 

Online resources 

These Web sites are also relevant as further information sources: 

► Description of Eclipse RCP from www.eclipse.org 

http://www.ecl ipse.org/downl oads/download.php?file=/technology/phoen 
ix/tal ks/What-is-Ecl ipse-and-Ecl ipse-RCP-3.2.6.ppt 

► Architectural Styles and the Desgn of Network-based Software Architectures 
http://www.ics.uci .edu/~fi el di ng/pubs/di ssertati on/top. htm 

http://www.surfscranton.com/architecture 
http://rest.bl ueoxen.net/cgi-bin/wi ki .pi TwhatlsREST 

► Ajax and REST, Part 1 

http://www.ibm.com/developerworks/web/! ibrary/wa-ajaxarch/ 
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► Restful Architecture 
http://www.surfscranton.com/architecture 

► RESTwiki 

http://rest.bl ueoxn.net/cgi-bin/wi ki .pl?whatIsREST 

► CICS TS Version 4.1 Information Center 
http://publib.boulder.ibm.com/infocenter/cicsts/v4rl/index.jsp 

How to get Redbooks 

You can search for, view, or download Redbooks, Redpapers, Technotes, draft 
publications and Additional materials, as well as order hardcopy Redbooks 
publications, at this Web site: 
ibm.com/redbooks 

Help from IBM 

IBM Support and downloads 
ibm.com/support 
IBM Global Services 
ibm.com/services 
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Extend the CICS Explorer 

A Better Way to Manage Your CICS 



Redbooks 


Add value to the CICS 
Explorer with Eclipse 
plug-ins 

Unlock the CICS 
Explorer Software 
Development Kit 

Follow examples of 
tool integration 


CICS Explorer is the latest significant evolution in the management 
and analysis of your CICS environment. It is a statement of intent 
from the CICS Development organization, which is determined to 
ensure you can manage your CICS estate in a simple and easily 
extensible way, using a combination of the following approaches: 

► Tried and trusted CICS expertise and technology 

► The widely accepted user interfaces and integration power of 
the open source Eclipse platform 

► Web 2.0 and RESTful programming (this technology underpins 
the CICS Explorer concept) 


INTERNATIONAL 

TECHNICAL 

SUPPORT 

ORGANIZATION 


BUILDING TECHNICAL 
INFORMATION BASED ON 


This IBM Redbooks publication shows how you can use the 
extensible design of CICS Explorer to complement the functionality 
already provided, with added functionality tailored to the needs of 
your business. We show you how to perform the following tasks: 


PRACTICAL EXPERIENCE 

IBM Redbooks are developed by 
the IBM International Technical 


► Install the CICS plug-in SDK into your eclipse environment 

► Develop a simple plug-in for the CICS Explorer 

► Deploy the plug-in into CICS Explorer 

We provide several useful examples of plug-ins that we developed 
during the residency using the methodology we describe. 


Support Organization. Experts 
from IBM, Customers and 
Partners from around the world 
create timely technical 
information based on realistic 
scenarios. Specific 


The starting point for the book is that you already have CICS 
Explorer installed and configured with connectivity to your CICS 
region or CICSPlex, and that you are looking for ways to customize 
CICS Explorer. 


recommendations are provided 
to help you implement IT 
solutions more effectively in 
your environment. 


SG24-7819-00 


For more information: 

ibm.com/redbooks 



